soa-quality-control

name	soa-quality-control
description	Guide a post-phase quality-control fix into one verified review-gap ledger record. Use for /soa quality-control phase-NN: <description> and /soa qc phase-NN: <description> after a small fix has exposed learning for future planning or review prompts. Also handles phase-unknown: <description> when the operator can't name the originating phase up front.

SoA Quality Control

Use this skill for the post-phase quality-control lane after closeout when a small, verified fix exposes a review gap worth recording.

Triggers:

• /soa quality-control phase-NN: <description>
• /soa qc phase-NN: <description>
• /soa quality-control phase-unknown: <description> or /soa qc phase-unknown: <description> — the operator knows the fix but not which phase produced the gap. This is a supported placeholder, not a missing argument; see Phase Attribution below.

A phase argument is required — either a concrete phase-NN or the literal placeholder phase-unknown. If it is absent entirely (neither form given), stop and ask for one before inspecting or changing files.

Scope

This is a guided fix-and-record lane, not a delivery-orchestrator command and not a replacement for /soa tao, standalone PR triage, or new phase planning.

Use it when:

• the phase has already closed out
• the issue is small enough for one bounded fix commit
• a human can verify the fix before capture
• the learning belongs in docs/product/review-gaps/ledger.jsonl

Route larger or unclear work toward standalone PR triage or /soa plan with a one-line explanation. Do not hard-gate solely on size when the operator is already asking for quality-control capture.

Workflow

1. Parse the phase argument (a concrete phase-NN, or the phase-unknown placeholder — see Phase Attribution) and the issue description.
2. Inspect the relevant code, docs, tests, prior phase tickets, and review artifacts needed to understand the reported gap.
3. Make the smallest prudent fix.
4. Verify with the narrowest meaningful command, then broaden if the touched surface warrants it.
5. Ask for or confirm human verification of the fixed behavior before recording the review gap. Do not append a ledger row for an unverified fix.
6. Commit the fix. The fix commit is the provenance for the ledger row.
7. Append exactly one JSONL record to docs/product/review-gaps/ledger.jsonl using the review-gap ledger helper contract from tools/delivery/review-gap-ledger.ts. Treat this as the record-review-gap step: one verified fix, one commit, one ledger line. Prefer the optional rich-capture fields (problem, solution, defectClass, testReachability, recurrence, id) whenever the fix exposes reusable learning — a one-line summary alone discards the experiential detail that makes the ledger valuable for future planning and review prompts.
8. If the learning may deserve future prompt or process changes, add a concise candidate to docs/product/review-gaps/promotion-queue.md.
9. Run formatting and the relevant verification command after editing the ledger or promotion queue.

Phase Attribution

phase-unknown defers phase resolution to this skill instead of the operator. Proceed through steps 2-6 of the Workflow normally — the fix itself does not depend on phase attribution. Resolve the concrete phase-NN before step 7 (recording), using this sequence:

1. Investigate provenance with the same rigor as the fix itself: git log/git blame on the touched files and their immediate dependents, docstrings or comments citing a ticket/phase ID, the commit that introduced the code path the bug lives in (not the commit that merely exposed it), and any adjacent docs/product/review-gaps/ledger.jsonl rows already recorded against the same feature surface.
2. Form a single best-evidence recommendation — not a list of candidates. If two phases are plausible, pick the one that introduced the behavior, not the one that most recently touched the file.
3. Present the recommendation and the evidence it rests on to the operator, and get explicit confirmation before recording. Never silently record a guessed phase — phase-unknown is a deferred decision, not permission to skip attribution.
4. If investigation surfaces no defensible attribution (the feature predates the phase history, or spans so many phases that no single one produced it), say so plainly and fall through to the phase-NN Stop Condition below rather than recording a weak guess.

The ledger schema has no phase-unknown value — docs/product/review-gaps/ ledger.jsonl records always carry the resolved concrete phase-NN from this process, exactly as if the operator had supplied it directly.

Recording Rules

• Record the phase that produced the learning, not the phase that applies the fix. For a phase-unknown entry, this is the outcome of Phase Attribution above.
• Use the landed fix commit SHA and subject for fixCommit.
• Count how many detection or review rounds were needed before the issue was found.
• Bias against review-reachable. Use it only when the ticket spec, diff, or persisted review artifacts show the reviewer had enough evidence at review time to catch the issue and the lesson maps to adversarial-review prompt vocabulary.
• Use spec-gap when the expected behavior was a genuine decision left missing or underspecified in the plan, ticket, or acceptance criteria — something a competent builder would have had to stop and ask about (a tie-break between two valid behaviors, a timeout or limit value, a multi-instance interaction). Bias against spec-gap for implied invariants: behavior so intrinsic to the feature that no competent spec enumerates it and no competent builder would ship it the other way ("the dismiss button dismisses", "save persists", "delete removes"). Apply the litmus test — would a competent person, given no spec, have built it right on instinct? If yes, it is not a spec-gap; a shipped violation is a qa-gap (nobody exercised it) or review-reachable (it was visible in the diff). Classifying a self-evident invariant as spec-gap launders an own-goal into a planning miss and leaves the real gap — verification or review — unaddressed.
• Use qa-gap when the issue required experiential, manual, or dogfood verification outside the normal code-review surface.
• Use completeness-gap when delivered scope was valid but missed adjacent work that should be shaped in future planning.
• Do not edit docs/template/delivery/adversarial-review-template.md from this lane. Capture promotion candidates only, and promote later only after recurrence or a clear high-severity single instance.

Stop Conditions

Stop and ask the operator when:

• the phase argument is missing entirely (neither a concrete phase-NN nor phase-unknown was given)
• a phase-unknown entry cannot be resolved to a concrete phase-NN after investigation (see Phase Attribution), or the operator has not confirmed the recommended attribution
• the fix is not small and bounded
• human verification has not happened and cannot be confirmed
• commit provenance is unavailable
• reachability classification is genuinely ambiguous after reading the evidence
• recording would require changing the ledger schema or overwriting existing docs/product/review-gaps/ content