Skills

Prerequisites

• A concrete diff or branch to review.
• The architecture assumptions the profile records.

Steps

1. Check that controller, service, and repository or mapper responsibilities stayed separated.
2. Check that business logic did not leak into the controller.
3. Check transaction boundaries, including multi-write operations.
4. Check that API responses expose DTOs rather than persistence entities.
5. Check validation at the request boundary and error handling on failure paths.
6. Check that new behavior has tests, not only that tests still pass.

Capabilities needed

• read_code
• read_docs

Outputs

• Findings ordered by severity, each citing a file and line.
• An explicit statement when no issue was found.

Verification

• Every finding names the file and the rule it breaks.
• Findings distinguish a defect from a preference.

Escalates when

• A finding is security relevant; hand it to security review.
• A finding touches schema or query behavior; hand it to SQL review.

Prerequisites

• A reproducible failure, a failing gate, or a concrete error report.

Steps

1. Reproduce the failure and record exactly how.
2. Narrow the failure to the smallest input or code path that still shows it.
3. State a hypothesis about the cause that could be proven wrong.
4. Test the hypothesis with the smallest possible probe.
5. Fix the cause rather than the symptom.
6. Add a regression test that fails before the fix and passes after it.
7. Re-run the declared gates.

Capabilities needed

• read_code
• run_tests
• edit_worktree

Outputs

• The reproduction steps.
• The root cause, stated plainly.
• The fix and the regression test that covers it.

Verification

• The failure was observed before the fix and is gone after it.
• The regression test fails when the fix is reverted.
• No unrelated code was changed while chasing the bug.

Escalates when

• The failure cannot be reproduced; report that rather than guessing at a fix.
• The cause lies in data or infrastructure that requires a denied capability.

Prerequisites

• A concrete diff or branch to review.
• The profile's stated component and routing assumptions.

Steps

1. Check the server and client component boundary and what that choice costs.
2. Check where data is fetched and how loading and error states are handled.
3. Check that types describe the real shape rather than widening to any.
4. Check keyboard access, focus visibility, labelling, and contrast.
5. Check behavior at narrow viewport widths, including no accidental horizontal overflow.
6. Check that state is owned at the right level rather than duplicated.

Capabilities needed

• read_code
• read_docs

Outputs

• Findings ordered by severity, each citing a file and line.
• Accessibility and responsive issues called out separately, because they are easy to defer and hard to retrofit.

Verification

• Every finding names the file and the rule it breaks.
• Accessibility claims describe the actual barrier, not a generic reminder.

Escalates when

• A finding depends on a backend contract; hand it to integration review.
• A finding involves authentication or data exposure; hand it to security review.

Prerequisites

• Work that is finished, blocked, or being paused.

Steps

1. State the goal in the requester's terms.
2. List what was actually completed, separately from what was attempted.
3. State the current status honestly, including partial work.
4. List changed files and the decisions behind them.
5. List blockers and the approaches that were tried and failed, so they are not repeated.
6. State the verification status of every claim.
7. List concrete next steps.

Capabilities needed

• read_code
• read_docs

Outputs

• A handoff record covering goal, completed work, status, changes, decisions, blockers, failed attempts, next steps, and validation.

Verification

• Another session could resume from the record alone.
• Every status claim matches evidence; unverified work is labelled unverified.
• Failed attempts are recorded rather than quietly omitted.

Escalates when

• The work is blocked on a decision only a human can make; say so in the record.

Prerequisites

• An approved plan.
• A working branch, never the default branch.

Steps

1. Work on a branch in an isolated worktree.
2. Make the smallest coherent change that satisfies one planned step.
3. Follow the layering and conventions the profile records as assumptions.
4. Add or update the tests that prove the new behavior.
5. Run the declared build and test commands.
6. Leave files the plan did not name untouched.

Capabilities needed

• read_code
• read_docs
• edit_worktree
• run_tests
• create_branch

Outputs

• A changed-file list with the reason for each change.
• Test additions covering the new behavior.
• Verification results, including any failure.

Verification

• The declared gates were run and their real results reported.
• A failing check is reported as failing and never suppressed or worked around.
• The diff contains no unrelated edits.

Escalates when

• A gate still fails after the declared retry limit.
• The change turns out to require a capability the role does not hold.
• Implementation reveals the plan was wrong; return to planning rather than improvising.

Prerequisites

• A stated requirement or reported problem.
• A resolved project declaration, so commands and architecture assumptions are known.

Steps

1. Restate the requirement in your own words and list what is still unknown.
2. Locate the entrypoints and modules the requirement touches.
3. Read the related code, tests, and declared context documents.
4. Record the architecture assumptions the profile states, which the change must preserve.
5. Write findings with file references, affected areas, risks, and open questions.
6. Stop before editing. Investigation ends with understanding, not a change.

Capabilities needed

• read_code
• read_docs
• github_read

Outputs

• Findings that cite specific files and symbols.
• A list of affected areas and the risks each carries.
• Open questions that a human must answer.

Verification

• Every claim points at a file, symbol, or command output.
• Anything not confirmed is written down as unknown rather than assumed.

Escalates when

• The requirement is ambiguous enough that two readings imply different work.
• Required context is missing, unreadable, or outside the project root.

Prerequisites

• Investigation findings for the requirement.
• Knowledge of which quality gates the project enables.

Steps

1. State the scope and, just as explicitly, the non-goals.
2. List the layers and files each step will touch.
3. Sequence the steps so that each one can be verified on its own.
4. Attach the verification command or check to every step.
5. Mark the points where a human must approve before continuing.
6. Confirm no step needs a capability the role does not hold.

Capabilities needed

• read_code
• read_docs

Outputs

• An ordered plan naming files and verification for each step.
• Explicit non-goals that keep unrelated refactoring out of scope.
• The approval points a human must clear.

Verification

• Each step names what it changes and how it is checked.
• The plan excludes cleanups the requirement did not ask for.

Escalates when

• The plan cannot work without a denied capability.
• The requirement turns out to be larger than the requester expects.

Prerequisites

• A concrete diff or branch to review.
• Knowledge of which endpoints and data the change touches.

Steps

1. Check that every new entrypoint authenticates and authorizes at the boundary.
2. Check that the change grants the least privilege that still works.
3. Check input validation and output encoding on untrusted data.
4. Check that secrets come from the environment and never appear in code, config, logs, or errors.
5. Check injection risk, including content an agent or model may read as instructions.
6. Check that security-relevant actions leave an audit trail.

Capabilities needed

• read_code
• read_docs

Outputs

• Findings describing the vulnerability class and the realistic impact.
• A clear statement of which risks were checked and found acceptable.

Verification

• Each finding names the entrypoint and the trust boundary it crosses.
• No finding, example, or diagnostic reproduces a real credential value.

Escalates when

• A credential appears to be committed or exposed; stop and notify a human at once.
• The finding is exploitable in production; escalate rather than fixing quietly.

Prerequisites

• The proposed schema or query change.
• Metadata-only access to the relevant schema.

Steps

1. Check column types, nullability, defaults, and constraints against the domain rules.
2. Check that queries are parameterized and never assembled by string concatenation.
3. Check indexes against the query shapes that will actually run.
4. Check transaction scope, isolation, and locking for multi-statement work.
5. Check that a migration is reversible, or state plainly that it is not.
6. Check what happens to existing rows, including rows that violate a new constraint.

Capabilities needed

• read_code
• database_metadata

Outputs

• Findings citing the statement or migration in question.
• An explicit note when a migration is destructive or irreversible.

Verification

• Index claims reference the query they are meant to serve.
• Data-loss risk is stated directly rather than implied.

Escalates when

• The change would drop or rewrite existing data; require human approval.
• Reviewing properly would need row data rather than metadata; stop and say so.

Prerequisites

• A resolved project declaration, so every enabled gate has a command.
• A working tree in the state that is meant to be tested.

Steps

1. Read the resolved commands rather than inventing one.
2. Run each enabled gate in the declared order.
3. Record the exit status and the relevant output for each gate.
4. Report a gate with no command as unavailable, never as passed.
5. Report a gate that was not run as unrun, never as passed.
6. Summarize which gates ran, which failed, and what the failure was.

Capabilities needed

• read_code
• run_tests

Outputs

• A per-gate result of passed, failed, unavailable, or unrun.
• The evidence behind each result.

Verification

• Every reported result corresponds to a command that actually ran.
• No gate is marked passed because it was skipped, disabled, or substituted.

Escalates when

• A declared command does not exist; report it unavailable rather than substituting another.
• A gate needs credentials, a database, or a network service that policy denies.