finding-discipline

Files (1)

• SKILL.md

SKILL.md (first lines)

# Finding discipline

Use this skill after you have inspected enough code to know a concrete runtime
failure or present maintenance cost. The goal is fewer, sharper findings that a
PR author can fix.

## Workflow

1. Treat reviewer output as candidate observations. For each runtime candidate,
   apply the likelihood-impact framework in [Risk rating](#risk-rating), then
   apply the finding bar in [Finding bar](#finding-bar).
2. Apply the three-gate actionability contract in
   [Actionability gate](#actionability-gate). Treat this as the required
   decision point for whether a candidate may produce a finding, code, or a
   test.
3. Drop excluded observations using [Exclusions](#exclusions).
4. Run the confirmation pass in [Confirmation pass](#confirmation-pass).
5. Write each finding with the format and severity rules in [Output](#output).
6. Perform the final review pass before presenting findings.

## Required discipline

- Optimize candidate generation for recall and finding acceptance for precision.
- Prefer no finding over a weak finding.
- Require reality, importance, and repair quality to pass independently.
  Repair quality may authorize either a supported repair or an owner
  consultation when the problem is proven but the repair is not. Neither path
  automatically authorizes a patch or test.
- Put only proven, deliberately tolerated risk in residual risk. Reject
  theoretical possibilities instead of preserving them as warnings.
- Merge duplicates under one root cause.
- Remove findings that depend on unproven assumptions.
- Check each line reference still overlaps the reviewed change when possible.
- Make titles action-oriented, not diagnostic labels.

## Risk rating

Treat reviewer output as a hypothesis. Rate severity only after proving a
current production path and a meaningful consequence.

### Risk reality check

Record this case before the findings CLI assigns severity and disposition:

```text
Production path: <current producer -> transformations -> failing sink>
Reachability evidence: <observed payload, current contract, or repository invariant>
Likelihood: likely | possible | rare | unknown | theoretical
Impact: critical | high | medium | low
Actual consequence: <verified behavior and meaningful user/system impact>
```

Use these likelihood meanings:

- `likely`: observed or reached by normal, recurring supported inputs.
- `possible`: a supported current path reaches it without an exceptional
  combination of events.
- `rare`: a supported current path exists, but requires an unusual input or
  state combination.
- `unknown`: evidence is missing. Investigate; do not guess a probability.
- `theoretical`: only an arbitrary type value, synthetic test, dependency
  maximum, or imagined state reaches it. Reject it.

Use these impact meanings:

- `critical`: exploitable security boundary, irreversible data loss or
  corruption, or broad outage.
- `high`: blocked core workflow, serious data or permission error, or many
  affected users.
- `medium`: bounded correctness or workflow failure with meaningful recovery
  cost.
- `low`: presentation defect, minor inconvenience, or easy recovery without
  material loss.

### Deterministic rating

Supply likelihood and impact. Do not choose severity or disposition; the
findings CLI derives the risk outcome from this table:

| Likelihood | Low impact | Medium impact | High impact | Critical impact |
| --- | --- | --- | --- | --- |
| likely | P3, accept | P2, accept | P1, accept | P0, accept |
| possible | no severity, reject | P2, accept | P1, accept | P1, accept |
| rare | no severity, reject | no severity, reject | P2, consult | P1, consult |
| unknown | no severity, investigate | no severity, investigate | no severity, investigate | no severity, investigate |
| theoretical | no severity, reject | no severity, reject | no severity, reject | no severity, reject |

Low-probability, low-impact risk defaults to no finding and no code. Severity
reflects likelihood and impact together; worst-case impact alone cannot raise a
finding. Supply `--handling fix|consult|follow-up|reject` separately: it routes a
proven finding without changing severity or turning a rejected or unproven risk
into work. Use `reject` with the failed actionability gate and rationale when a
candidate does not deserve intervention. A contained systemic repair may use
`fix`; a material systemic repair uses `consult` before editing. When the owner deliberately
defers an accepted local finding, the CLI records it as residual risk without
changing its severity. The owner may reject a consulted finding without turning
it into an autonomous patch; the terminal update records that separate decision
with `--owner-resolution`. An unanswered consult stays open. A real adjacent
issue uses `follow-up`, is reported as deferred work, and does not block the
current review.

### Disposition

- `accept`: non-synthetic evidence proves the path and consequence, the table
  makes action worthwhile, and the behavior violates a current contract.
- `investigate`: reachability, likelihood, or sink behavior is still unproven.
  Gather evidence; do not patch.
- `consult`: the risk is proven, but tolerance or scope is a product, security,
  compatibility, operational, or architectural choice. Ask before patching.
- `follow-up`: the issue is real but belongs outside the current review. Record
  the owner or next action without blocking the current PR.
- `residual`: the risk is proven and the current change deliberately leaves it
  unresolved. Record it without patching.
- `reject`: the path is theoretical, the combined risk does not justify code,
  or the current contract explicitly allows the proven behavior.

The burden of proof belongs to the finding. A test created from the reviewer's
example can verify a fix after acceptance; it cannot supply missing production
evidence.

From jesse-merhi/skills, MIT.

More from jesse-merhi/skills