kumouri/zethus

Recover the scheduling contract -- frequency, dependency ordering, calendar exceptions, and the environment a job silently relies on -- from crontab entries or a scheduler product's job-definition export such as Control-M, and map inter-job ordering onto the modernization target (a Spring Batch job flow by default, or a cloud workflow orchestrator such as AWS Step Functions). Use as the batch-type/cron-scheduler-wrappers reader within recover-business-rules whenever a batch estate's ordering lives in a scheduler rather than in application code.

Recover business rules from ksh (and adjacent POSIX shell) batch drivers -- argument parsing, exit-code contracts, trap/signal handling, file locking, and retry/backoff loops -- as first-class rules rather than incidental scripting. Use as the batch-type/ksh-scripts reader within recover-business-rules whenever a batch job is driven by a ksh wrapper, alone or in front of a Spring JAR or a call into stored procedures.

Recover business rules from plain Spring applications that hand-roll batch loops over JPA/JDBC with no Spring Batch framework -- where "a batch" is only a main() and a loop, and commit points and restart behaviour must be inferred from transaction boundaries in code rather than read off framework config. Use as the batch-type/spring-jpa-jdbc reader within recover-business-rules for the ask's named first target, old Spring-based JPA/JDBC batches.

Recover business rules from Oracle 12c-era PL/SQL — packages, triggers, autonomous transactions, %TYPE/%ROWTYPE, bulk collect/FORALL, WHEN OTHERS handlers, sequences, materialized views — from a source-controlled DDL repo or DDL extracted from a live database, and record a keep/wrap/port disposition per procedure against the target HLA's default. Use as the dialect/oracle-plsql reader within recover-business-rules whenever a batch job calls Oracle stored procedures.

Before the pre-push gates and the PR, find the documentation that describes the code this change touched and confirm each is still true — updating it in place in the same change — and check every Markdown pointer still resolves. Uses docs-pointer-check with the docSync map. Use before opening a PR, after renaming or moving files, or when asked whether the docs are up to date.

Investigate a failure with fresh eyes — given only the failing artifact (log, test output, stack trace, diff) and one line of intent, return a ranked list of places to look, each marked established (with what was read) or conjecture. Never a diagnosis, never a fix; an empty list is a valid answer. Use when an approach has failed twice, when a failure makes no sense, or when you're stuck and have a theory you can't shake.

Implement exactly one phase of a signed-off spec on its own branch (or as one commit series on a long-lived branch, in rebase style) — Phase 0 first, which changes no behaviour — keeping the diff inside the phase, flagging anything the spec didn't cover instead of silently deciding it, and recording deviations as an "As built" list. Use when a spec has been signed off and it's time to write code, or when resuming a phase.

Run every lint, build and test gate CI would run, locally on the working tree, before pushing — and report the result honestly, where a skipped gate is not a passed gate. Uses run-local-gates for a PASS/FAIL table to paste into the PR. Use before any push, before opening or updating a PR, or when asked "is this ready".

Recover implicit business rules from legacy source before a modernization touches it, in the shape of research-existing-code but aimed at legacy code instead of a live-codebase question. Turns a magic number, an unexplained null check, a swallowed exception, or a commented-out branch into an explicit, numbered, file:line-cited rule with a confidence level. Use at Stage 1 (Research) of any modernization engagement, before writing the constitution, and before any legacy source is rewritten, wrapped, or ported.

Research how existing code actually behaves before specifying or changing it. Produces a facts table where every claim is cited to file:line, records the search behind each negative claim, and states what the research did not cover. Use before writing a spec, before estimating, when asked "how does X work" or "what calls Y", or when inheriting someone else's claims about a codebase.

Translate a Markdown spec (a Zethus spec or any spec-shaped Markdown) into a set of Jira-ready stories, one Markdown file per story plus an index — each with a user-value title, a user story statement where it fits, 2-4 sentences of context, testable acceptance criteria, out-of-scope, dependencies, a traceability link back to the spec section, and optional sizing notes with no invented story points. Every story carries an explicit INVEST self-check and a flag on any criterion it fails; epics group stories when the spec has phases. Produces drafts only — nothing is created in Jira without explicit human approval in this session. Use when a spec is signed off, or far enough along, and needs to become a batch of stories, or when asked to turn a spec into stories or tickets.

Research one or more existing Jira stories against the real codebase, cited to file:line via research-existing-code, and produce an enriched version — what it actually touches, current behaviour, tightened or added acceptance criteria, risks and edge cases, and open questions for the PO — human-relevant only, no agent chatter, stack traces, or code dumps. Detects available Jira access (an Atlassian/Jira MCP tool, the jira/acli CLI, or REST via an env token) and degrades to pasted story text when none is available. Outputs a proposed update plus a diff against the original; nothing is written back to Jira without explicit human approval. Use when a story needs fleshing out before estimation or before work starts, or when asked to enrich, flesh out, or research a ticket.

Plan and verify the tests for a change — per phase, what each test proves, at what level, including the refusal and failure paths, plus a mutation check that the key test actually fails without the change. Use when filling a spec's Test plan section, before implementing a phase, or when asked "how should we test this" or "are these tests enough".

Classify every recovered HttpSession / ActionForm session-scope / @SessionAttributes / session-scoped bean attribute into one of five stateless destinations, and decide the auth strategy (shim vs. replace) the target HLA names. First-class in v1, not deferred — a flow can't be marked migrated while any of its session attributes is unclassified or still read from HttpSession by the new code. Use after the webapp-target readers have recovered session attributes, before a flow's cutover unit may be marked migrated.

Group recovered routes into strangler-fig cutover units — per-screen-flow where routes share session state, per-route otherwise — exclude routes already migrated to REST/a new frontend, and order session-state extraction before cutover for any unit that depends on it. Use once the webapp-target readers have emitted route manifests for a target, before Stage 3 (Implement) plans which route or flow to build next.

Recover routes, container-managed authz, session lifetime, inline scriptlet/JSTL business logic, and raw HttpSession usage from web.xml and plain JSP/servlet source — the third (ranked) and most rule-dense legacy web-app target, since business logic routinely lives inline in the page. Use as the webapp-target/plain-jsp-servlets reader within recover-business-rules whenever a target estate has JSP pages with scriptlets or JSTL, or servlets with no framework, and as the shared HttpSession scan for any other reader's Java sources.

Recover routes, JSP view resolution, session attributes, method-security authz, hybrid Struts delegation, and already-migrated-to-REST detection from old Spring MVC controller source — the second (ranked) legacy web-app target. Use as the webapp-target/spring-mvc-jsp reader within recover-business-rules whenever a target estate has @Controller classes rendering JSP views, including a hybrid where the controller wraps or invokes a Struts Action/ActionForm and where some routes are already served by REST.

Recover routes, action/form mappings, validation, session-scoped ActionForms, and roles-based authz from Struts 1.x and 2.x config, plus optional Java sources for hybrid Spring-controller-delegates-to-Struts detection — the first (ranked) legacy web-app target. Use as the webapp-target/struts reader within recover-business-rules whenever a target estate has struts-config.xml or a struts.xml, including a hybrid where Spring MVC wraps or invokes a Struts Action/ActionForm.

Record a decision as an Architecture Decision Record — one imperative decision sentence, context, options with the chosen one marked, consequences, where the decision is enforced, and when to revisit it. Plain Markdown that pastes cleanly into a wiki page or ticket. Use whenever a decision is made in chat, a meeting, a spec review or a PR thread, or when a spec's open question is answered.

Write a full specification for a change that spans more than one PR, has a measurement behind it, or has decisions a reviewer will want to argue with. Covers the verbatim ask, measured problem, cited facts, assumptions checked, options with a recommendation, phases where Phase 0 changes no behaviour, test plan, rollback, out-of-scope, and open questions — then stops for sign-off. Use when asked to spec, design, or plan a non-trivial change.

Write a one-screen minimum spec for a change that fits in one PR — the verbatim ask, a cited facts table, the design, phases (Phase 0 changes no behaviour), a test plan, out-of-scope, and open questions with a recommendation — then stop for sign-off. Use for small behaviour changes, bug fixes that change behaviour, and whenever someone says "just code it" (this is the fast path).

Write a pull request description with evidence — what and why, linked spec and ADRs, the local gate table, tests and what they prove, what was NOT checked, deliberate deferrals, and decisions needed from the reviewer — diffed against the repo's real integration branch. Use when opening or updating a PR, or when asked to summarize a branch for review.