ensure-quality

Ensure quality

Inner-loop quality gate: risk/correctness review plus anti-AI-slop. Asks whether the change will break, leak, or silently undo what the user wanted, and catches parallel structure, hand-synced catalogues, phantom names, and other common agent failure modes early. Moves review, test, docs, and lint closer to the work before it leaves the machine. No daemon, no second worktree, no push/PR - this skill is the gate. To gate then commit and open a triage PR, use to-quality-pr.

Self-contained: everything needed lives under this skill folder. Project-agnostic: discover how this repo tests, lints, documents, and states maintainability rules - do not assume a stack.

Stages (order): review → test → document → lint. Load each stage file only when that stage runs. Load reference/discover.md once during preconditions. Anti-slop baseline: reference/anti-slop.md (always on during review; repo rules override on conflict).

When to run

Fire this skill when any of these hold:

• The user asks to ensure quality / validate / gate / check before commit.
• You just finished substantive source changes (feature, fix, refactor).
• You are about to create a git commit (local only). If the next step is also a pull request, invoke to-quality-pr instead.

Skip auto-invoke for pure Q&A, exploration with no edits, or when the user said to keep iterating without gating.

Preconditions

1. Synthesize intent. Capture what the user set out to accomplish - goal, constraints, tradeoffs, ruled-in/out approaches - in their terms, enriched with decisions you made while working. A thin "fixed stuff" line is not enough; rewrite from conversation context first. This intent is authoritative acceptance criteria for the review stage.
2. Discover the project. Follow reference/discover.md. Record the chosen test commands, lint commands, standards sources, anti-slop / maintainability docs, checklists, and doc surfaces for this run.
3. Pin the fixed point. Default: merge-base of the current HEAD (and dirty worktree) against the first existing of: upstream tracking remote's default branch, then origin/develop, origin/main, origin/master, then local develop / main / master. Honor an explicit user override (since abc123, origin/main, …). Confirm the ref resolves.
4. Scope the diff. Include committed commits since the fixed point and uncommitted/staged work. Warn if on a default branch; still proceed.
5. Skip flags. Run all four stages unless the user explicitly skips one (skip lint, lint only, …). Auto-invoke never skips.

Completion: intent written, discovery recorded, fixed point named, diff non-empty (or report ready with nothing to gate and stop).

Pipeline loop

For each stage in order:

1. Read stages/<stage>.md and run it.
2. Collect findings using the taxonomy in reference/findings.md.
3. Auto-fix every auto-fix finding without asking, then re-run the stage. Cap at 2 auto-fix rounds for that stage; leftover findings escalate to HITL.
   • Review stage: auto-fix is mechanical one-liners only. After any review fix, follow the root-cause fixer rules and adversarial re-review in stages/review.md (treat fixer output as untrusted new code).
   • Test / document / lint: mechanical/low-risk auto-fix as each stage file allows.
4. If any ask-user findings remain, pause - see HITL pause. Do not start the next stage until the pause resolves.
5. no-op findings are reported only; nothing to do.
6. If the stage stays red after rounds / declined fixes, go to Blocked.

Leave all quality fixes uncommitted unless the user already asked you to commit or ship.

HITL pause

Batch every current-stage ask-user finding in one message. Present each like a grill round - question, options, recommendation - then wait. When review recorded risk_level: high, prefer recommending careful fix over casual approve/skip.

⏸ **Quality gate - <stage>** (<n> ask-user findings)

❓ **F1** - **<short title>**: <verbatim finding: file, description, why it challenges intent or product behavior>

Options:
- **fix** - apply a fix (optionally with your guidance)
- **approve** - accept as-is and continue
- **skip** - drop this finding for this run
- **abort** - stop the whole gate

➡️ <your recommended option and one-line why>

Translate the user's answers into actions, apply agreed fixes, re-run the stage, then continue. For review-stage fixes agreed in HITL, still apply fixer discipline and adversarial re-review from stages/review.md. Do not paraphrase away finding detail. Do not continue past unresolved ask-user findings.

Blocked

Stop the pipeline. Leave fixes dirty. Emit the Summary with Ship readiness: blocked and the remaining findings. Do not commit. Do not claim green. Do not silently skip the failing stage.

Summary

Always end a completed or blocked run with this fixed brief (this order):

1. Intent - short paragraph
2. Risk - Low / Med / High + one sentence why (use the review-stage risk assessment when review ran)
3. Diff scope - fixed point → worktree; key files
4. Findings - counts by stage; call out risk-lens and anti-slop hits; auto-fixed vs HITL vs accepted vs remaining
5. Tests run - commands + pass/fail; note skipped suites and why
6. Docs - updated / checked / none needed
7. Lint - commands + result
8. Ship readiness - ready or blocked + what's left
9. Uncommitted fix set - bullets if any quality fixes were applied