Senior Engineering

Core rule: spend the process the risk justifies — no less on risky work, no more on trivial work.

1. Establish the goal

Extract:

• the desired outcome and how someone would observe it;
• acceptance criteria you can check;
• constraints and non-goals;
• whether the request is implementation or only analysis/planning.

Do not invent requirements that the repository or the request already answers.

2. Read only relevant context

In this order, stopping when you have enough:

1. repository instructions (AGENTS.md, CLAUDE.md or the host equivalent);
2. .senior/project.json and only the decisions relevant to this task;
3. files directly implicated by the task;
4. nearby tests and analogous implementations;
5. external documentation, only when local version/API evidence is insufficient.

A small local change does not need a repository map.

3. Classify risk

If the senior CLI is available, run senior risk once you know which files change; after work is committed on a branch, run senior risk --base <ref> (for example main). Treat the score as a floor and raise it when the task semantics are riskier than the paths suggest.

Plan before the first edit when the design can be wrong. Write a short plan now, before editing, when the change has several steps at medium risk or above, renames or reshapes a field, key or type that other modules or saved data read (whatever the risk score says), or does something that can fail halfway (a payment or refund, stock, an external call). In a few lines: the acceptance criteria; every reader and writer of what changes, found by searching (code, tests, scripts, saved data); what happens if a step fails after an earlier one took effect, if the call runs twice, and if it meets old data or an old caller; and the test that proves each of those. A plan written after the code is a report, not a plan.

4. Implement the minimum coherent change

• follow existing project patterns unless there is a concrete reason not to;
• avoid unrelated cleanup and new dependencies when existing primitives suffice;
• update tests next to the behavior that changes;
• where caller input reaches stored state or a privileged operation (a request body, query, path, id or file name), decide what each kind of caller may control and enforce it in the code: pick the allowed fields instead of spreading or assigning the whole input, scope lookups to what the caller may access, and add a test where a caller sends something they must not control;
• when uncertainty matters, verify it instead of compensating with more code.

5. Prove the outcome

Run the repository's real checks. senior finish runs the standard package-script baseline; add task-specific evidence (the original reproduction, a browser flow, an API call) when the baseline cannot prove the outcome. A skipped or unavailable check is never a pass.

When the repository shows the real volume (a seed, a config value, a sample file, a note on production size), run the changed path at that volume through its public entry point before saying done, and fix what is slow, including the helpers it calls.

6. Review the diff

• Does it satisfy the goal, and only the goal?
• Is there a simpler implementation?
• Are error paths and edge cases covered?
• Did security, data integrity, performance or compatibility risk change?
• Is there leftover debug code, dead code or a misleading comment?

For medium risk and above, use senior-code-review.

7. Close with evidence

Report what changed, what was actually verified, what was skipped, and the residual risk that still matters. Use senior-finish before claiming the work is done.

When the process starts to slip

These apply at medium risk and above.

And the reverse, at low risk: if you are writing a plan, spawning reviewers or asking clarifying questions for a one-line fix, stop and just do it.