# Quality Gate Review > [Project Management] Use when you need to enforce quality gates, verify compliance with standards, track quality metrics, and generate audit trails. - Skill: `duc01226/quality-gate-review` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/quality-gate-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/quality-gate-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/duc01226/quality-gate-review --- > Codex compatibility note: > > - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references. > - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. > - User-question prompts mean to ask the user directly in Codex. > - Ignore Claude-specific mode-switch instructions when they appear. > - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. > - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task. > - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. > - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. > - If a required step/tool cannot run in this environment, stop and ask the user before adapting. ## Codex Project-Reference Loading (No Hooks) Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing. **Always read:** - `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings) - `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog) - `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns) **Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it. **Situation-based docs:** - Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md` - Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md` - Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md` - Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md` - Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above - Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/` - Integration test implementation/review: `integration-test-reference.md` - E2E test implementation/review: `e2e-test-reference.md` - Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task. ## Quick Summary **Goal:** Enforce quality gates, verify compliance with standards, and track quality metrics across the development lifecycle. > **Renamed:** formerly `/qc-specialist` — that name no longer resolves as a slash command; use `$quality-gate-review`. **Workflow:** 1. **Identify Gate** — Determine which quality gate applies (Idea>PBI, PBI>Dev, Dev>QA, QA>Release) 2. **Verify Checklist** — Run through pass/fail criteria for the gate stage 3. **Generate Report** — Produce PASS/FAIL/CONDITIONAL gate status with evidence 4. **Track Metrics** — Log in audit trail and update quality metrics dashboard **Key Rules:** - Every gate must have a clear PASS/FAIL/CONDITIONAL status - Evidence must be provided for critical checklist items - Sign-offs are required before release gates can pass **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** # Quality Gate Review Enforce quality gates, verify compliance with standards, track quality metrics, and generate audit trails across the development lifecycle. --- ## Core Capabilities ### 1. Quality Gates Define pass/fail criteria at each stage: #### Gate: Idea → PBI - [ ] Problem statement present - [ ] Business value articulated - [ ] No technical solution prescribed - [ ] Target users identified #### Gate: PBI → Development - [ ] Acceptance criteria in GIVEN/WHEN/THEN - [ ] Out of scope defined - [ ] Dependencies identified - [ ] Design approved (if applicable) #### Gate: Development → QA - [ ] Code review approved - [ ] Mutation score meets target; surviving mutants triaged (line-coverage diagnostic only — not a gate) - [ ] No P1/P2 linting errors - [ ] Documentation updated #### Gate: QA → Release - [ ] All test cases executed - [ ] No open P1/P2 bugs - [ ] Regression suite passed - [ ] PO sign-off received #### PO Acceptance Decision (per-AC verdict — how "PO sign-off received" is earned) For each acceptance criterion from the PBI/story: 1. **Read criterion** — Ensure it's testable and measurable 2. **Check evidence** — Review test results, screenshots, demo recordings 3. **Verify** — Does the implementation satisfy the criterion? 4. **Verdict** — PASS or FAIL with specific evidence **Decision rules:** Every acceptance criterion must have a PASS/FAIL verdict. REJECT must list the specific items that failed. CONDITIONAL ACCEPT must list conditions and a timeline. ``` ## Acceptance Decision **Feature/PBI:** {Reference} **Reviewer:** {PO name/role} **Date:** {date} **Verdict:** ACCEPT | REJECT | CONDITIONAL ACCEPT ### Criteria Review | # | Criterion | Verdict | Evidence | |---|-----------|---------|----------| | 1 | {AC text} | PASS | {Evidence} | | 2 | {AC text} | FAIL | {Why it failed} | ### Decision Details - {Rationale for overall verdict} ### Conditions (if CONDITIONAL) - {Condition — deadline} ### Rejected Items (if REJECT) - {Item — what needs to change} ``` #### Verdict Validation Gate (why-review — MANDATORY before emitting REJECT/CONDITIONAL or any FAIL criterion) > **Purpose:** ACCEPT/REJECT/CONDITIONAL is a JUDGMENT. Validate it adversarially before it is emitted so a wrong verdict or a mis-classified FAIL criterion does not gate a release on ground that does not hold. This gate validates the verdict only — it routes any required fix back to the owning team/sibling review, it does NOT self-converge a fix-loop. **Trigger:** Any REJECT, any CONDITIONAL ACCEPT, or any criterion marked FAIL. Skip ONLY when every criterion PASSES with an unconditional ACCEPT. **Protocol:** 1. Read the finalized gate report (the Acceptance Decision above) from `plans/reports/{skill}-{date}-{slug}.md` (or the exact report path written). 2. Invoke `$why-review --validate-findings ` — verify each FAIL criterion and each stated condition has `file:line` / evidence proof and clears why-review's finding-survival bar. 3. **If why-review demotes/removes any FAIL criterion or condition:** update the verdict and criteria table, then add a `## Why-Review Validation Notes` section citing what changed and why. 4. **If the verdict changed after validation:** re-run this gate — maximum 2 validation passes — until the remaining FAIL criteria/conditions are validated. No fix-loop: this skill decides the gate and routes fixes to the owning team; it never restarts a full review over its own fixes. **Anti-bias (MANDATORY before emitting):** steel-man the OPPOSITE verdict — argue for ACCEPT if about to REJECT, and for REJECT if about to ACCEPT; the verdict that survives its own counter-argument ships. A gate decision that was never challenged is not validated. ### 2. Compliance Verification - Code follows architecture patterns - Security requirements met - Accessibility standards (WCAG 2.1 AA) - Performance benchmarks ### 3. Audit Trail Track artifact lifecycle: ``` {Artifact} | {Action} | {By} | {Date} | {Notes} ``` ### 4. Quality Metrics #### Code Quality - Cyclomatic complexity - Mutation score (line-coverage diagnostic only — not a gate) - Technical debt ratio - Duplication % #### Process Quality - Defect escape rate - First-time-right % - Cycle time - Lead time --- ## Quality Gate Checklists ### Pre-Development Checklist ```markdown ## Quality Gate: PBI Ready for Development **PBI:** {PBI-ID} **Reviewer:** {Name} **Date:** {Date} ### Requirements - [ ] Clear problem statement - [ ] User value articulated - [ ] Acceptance criteria in GIVEN/WHEN/THEN format - [ ] Out of scope explicitly listed ### Design - [ ] Design spec approved (if UI changes) - [ ] API contract defined (if backend changes) - [ ] Database changes documented (if applicable) ### Dependencies - [ ] Upstream dependencies identified - [ ] No blocking dependencies - [ ] Integration points documented ### Gate Status: PASS / FAIL / CONDITIONAL **Notes:** {Any concerns or conditions} ``` ### Pre-QA Checklist ```markdown ## Quality Gate: Ready for QA (Dev → QA) **Feature/PBI:** {Reference} **Reviewer:** {Name} **Date:** {Date} ### Readiness - [ ] All acceptance criteria implemented - [ ] Unit tests passing - [ ] Code review complete - [ ] No known critical bugs - [ ] Test data prepared ### Gate Status: PASS / FAIL / CONDITIONAL **Notes:** {Any concerns or conditions} ``` ### Database Performance gate (applies to all stages) - [ ] Database performance (pagination on all list queries; indexes on filter/FK/sort columns) — verified via `$production-readiness-review` and `$performance-review` ### Pre-Release Checklist ```markdown ## Quality Gate: Ready for Release **Feature:** {Feature name} **Release:** {Version} **Date:** {Date} ### Testing - [ ] All test cases executed - [ ] Pass rate: \_\_\_\_% - [ ] No open P1 bugs - [ ] No open P2 bugs (or exceptions approved) ### Code Quality - [ ] Code review approved - [ ] Mutation score meets target; surviving mutants triaged (line-coverage reported as a diagnostic only, no threshold) - [ ] No security vulnerabilities - [ ] Performance benchmarks met ### Documentation - [ ] User documentation updated - [ ] API documentation current - [ ] Release notes drafted ### Sign-Offs - [ ] QA Lead: **\*\***\_**\*\*** Date: **\_\_\_** - [ ] Dev Lead: **\*\***\_**\*\*** Date: **\_\_\_** - [ ] PO: **\*\*\*\***\_\_**\*\*\*\*** Date: **\_\_\_** ### Gate Status: PASS / FAIL **Release Decision:** {Go / No-Go with notes} ``` --- ## Workflow Integration ### Running Quality Gate When user runs `$quality-gate {artifact-or-pr}`: 1. Identify gate type based on artifact/stage 2. Load appropriate checklist 3. Verify each criterion 4. Generate pass/fail report 5. Log in audit trail --- ## Metrics Dashboard Template ```markdown ## Quality Metrics - Sprint {N} ### Code Quality | Metric | Target | Actual | Trend | | -------------- | --------------- | ------ | ----- | | Mutation score | meets target | | ↑↓→ | | Line coverage | diagnostic only | | ↑↓→ | | Complexity | <15 | | | | Duplication | <5% | | | | Debt Ratio | <10% | | | ### Process Quality | Metric | Target | Actual | | ----------------- | ------ | ------ | | Defect Escape | <5% | | | First-Time-Right | >90% | | | Avg Review Cycles | <2 | | ### Defect Trends | Sprint | Found | Fixed | Escaped | | ------ | ----- | ----- | ------- | | N-2 | | | | | N-1 | | | | | N | | | | ``` --- ## Output Conventions ### File Naming ``` {YYMMDD}-qc-gate-{stage}-{slug}.md {YYMMDD}-qc-audit-{feature}.md {YYMMDD}-qc-metrics-sprint-{n}.md ``` --- ## Quality Checklist Before completing QC artifacts: - [ ] All checklist items verified - [ ] Evidence provided for critical items - [ ] Sign-offs captured - [ ] Gate status clearly stated - [ ] Audit trail updated ## Related - `spec` - `code-review` --- > **[IMPORTANT]** Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip. - `docs/project-reference/domain-entities-reference.md` — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. > **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. > **Sequential Thinking Protocol** — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe. > > **Trigger when:** complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation. > > **Format (explicit mode — visible thought trail):** > > 1. `Thought N/M: [aspect]` — one aspect per thought, state assumptions/uncertainty > 2. `Thought N/M [REVISION of Thought K]: ...` — when prior reasoning invalidated; state Original / Why revised / Impact > 3. `Thought N/M [BRANCH A from Thought K]: ...` — explore alternative; converge with decision rationale > 4. `Thought N/M [HYPOTHESIS]: ...` then `[VERIFICATION]: ...` — test before acting > 5. `Thought N/N [FINAL]` — only when verified, all critical aspects addressed, confidence >80% > > **Mandatory closers:** Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete. > > **Stop conditions:** confidence <80% on any critical decision → escalate by asking the user directly · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task. > > **Implicit mode:** apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy). > > **Deep-dive:** see `$sequential-thinking` skill (`.claude/skills/sequential-thinking/SKILL.md`) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades). > **Goal Contract Satisfaction Loop** — Persist the user goal in an external file, execute against it, and loop review/fix until every saved required criterion passes or a blocker escalates. Bounded closed loop — NEVER open-ended autonomous exploration. > > 1. **Resolve the active goal** (in order): active plan `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md` → create a new Goal Contract from the current user request (template: `.claude/templates/goal-contract-template.md`). > 2. **Required sections:** Original Request, Purpose, Success Criteria (checkboxes; mark required vs optional), Constraints, Evidence Required, Iteration Log, Goal Satisfaction matrix. > 3. **Before work:** read the active goal and map planned work to saved success criteria — execution serves the saved criteria, never chat memory alone. > 4. **After execution/verification:** append an Iteration Log entry — result, evidence references (`file:line`, command output, report path), remaining gaps. > 5. **Review gate:** emit a Goal Satisfaction matrix — `| Success Criterion | Evidence | Status |` with PASS/FAIL/BLOCKED. Overall PASS requires every required criterion PASS. > 6. **Loop rule (retry):** required criterion FAIL → validate the gap is real → fix → re-review only the affected criteria. Stop cleanly when all required criteria PASS. > 7. **Escalation rule (stop):** two consecutive iterations with no criterion progressing, or a blocker needing user input → mark the criterion BLOCKED with a user-facing reason and escalate. NEVER loop indefinitely. > 8. **Skip rule:** tiny conversational tasks may skip the goal file ONLY with a recorded one-line reason. User-accepted gate skips are recorded in the goal file with reason and scope. > 9. **Security:** NEVER store secrets, tokens, credentials, or private customer data in goal files — store evidence references and redact sensitive values. > > **Blocked until:** active goal resolved (or skip reason recorded) · saved success criteria read before edits · iteration evidence appended after execution · Goal Satisfaction matrix emitted before any PASS verdict. > **Trade-Off Interrogation Gate** — ALWAYS ask these THREE questions before ANY verdict, score, finding, or recommendation — about the thing under review AND about every recommendation YOU make. — why: naming a benefit without its price is an endorsement, not a review; the costliest trade-offs are the ones nobody wrote down. > > 1. **Is there any trade-off?** Name what it SACRIFICES. "None" / "pure win" is an unfinished analysis, NOT an answer — to claim none, state which dimensions you checked and why each is unaffected: future change cost · complexity · performance/latency · memory/cost · coupling · reversibility · migration burden · operational load · blast radius · security posture · testability · team skill/ramp · delivery time · UX. > 2. **Is it worth it?** Weigh gain against sacrifice EXPLICITLY — what is gained (with a metric) · what it costs · WHO pays · WHEN it comes due — then emit **WORTH IT / NOT WORTH IT / UNCLEAR**. "Better" with no metric and no cost FAILS this question. NOT WORTH IT → withdraw or replace the recommendation, never keep it as-is. > 3. **Is the trade-off material enough to CONFIRM WITH THE USER?** A material trade-off is the user's call, never yours. **MATERIAL** when ANY holds: irreversible / one-way door (data migration, public contract, storage format, vendor lock-in) · cost shifted onto someone else (another team, ops/on-call, future maintainer, end user) · one quality attribute traded for another (correctness↔speed, security↔convenience, latency↔cost, simplicity↔flexibility) · a boundary crossed (client↔server tier, service contract, event contract, shared library) · a high-consequence path (auth, money, data integrity, breaking change, High/Medium residual risk) · the worth-it verdict is UNCLEAR. > > **MATERIAL → STOP and confirm by asking the user directly BEFORE the verdict stands** — state the trade-off, both options, what each sacrifices, and your recommendation. **NOT material →** record it inline with a one-line justification and proceed. > > **Non-asking execution contexts — ESCALATE BY HANDOFF, never by silence.** ask the user directly reaches only the main interactive agent: a sub-agent cannot ask the user, and a terminal/verdict-only mode asks nothing by design. When you are running in such a context, the obligation is **redirected, never waived** — do ALL of: (a) complete questions 1 and 2 normally; (b) decide materiality and record it in the Trade-Off Assessment row with `confirmed? = NO — cannot ask from this context`; (c) **name the unconfirmed MATERIAL trade-off explicitly in your returned summary/verdict so the CALLER (or parent orchestrator) escalates it by asking the user directly on your behalf** — a material trade-off mentioned only inside a report file on disk is NOT a handoff; (d) do not emit an unqualified PASS — mark the verdict as carrying an unconfirmed material trade-off, so the caller's gate stays closed until the user answers. The caller inherits the escalation duty the moment it reads your return. > > This carve-out is about **reachability, not convenience**: it applies ONLY where the tool genuinely cannot reach the user (spawned sub-agent, terminal validate/verdict-only mode, non-interactive/headless run). It is NEVER a licence to skip the question, to self-approve a one-way door, or to downgrade materiality because asking is inconvenient — if you CAN ask, you MUST ask. > > **Emit a Trade-Off Assessment row** per reviewed decision and per recommendation: `| decision | sacrifices | gain (metric) | who pays, when | WORTH IT/NOT/UNCLEAR | material? | confirmed? |`. > > **BLOCKED until:** trade-off named (or dimensions-checked justification given) · worth-it verdict emitted · materiality decided · every MATERIAL trade-off either confirmed with the user OR — in a non-asking context — handed off in the returned verdict for the caller to confirm. A MATERIAL trade-off that is neither confirmed nor handed off can NEVER be PASS, and NEVER gets buried as a Low-severity note. > > **NEVER** answer "no trade-off" without checking · decide a material trade-off silently on the user's behalf · let convergence/delivery pressure authorize walking through a one-way door · bundle several material trade-offs into one vague "proceed?". **MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence. **MUST ATTENTION** apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see `$sequential-thinking` skill. **MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting. - **MANDATORY** Resolve the active Goal Contract BEFORE work (active plan `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md` → create from current request) and read saved success criteria before editing. - **MANDATORY** Append iteration evidence after execution; emit a Goal Satisfaction matrix (PASS/FAIL/BLOCKED) before reporting PASS; loop on validated FAIL; escalate repeated no-progress or blockers. NEVER store secrets in goal files. - **MANDATORY MUST ATTENTION ALWAYS ASK THE 3 TRADE-OFF QUESTIONS** — on the thing under review AND on every recommendation you make: (1) **is there any trade-off?** name what it SACRIFICES (change cost · complexity · perf · coupling · reversibility · migration · ops load · blast radius · security · testability · delivery time · UX) — "none"/"pure win" is an unfinished analysis, so state the dimensions checked; (2) **is it worth it?** gain (with a metric) vs cost, WHO pays, WHEN → emit **WORTH IT / NOT WORTH IT / UNCLEAR**; NOT WORTH IT → withdraw or replace it; (3) **is it material enough to confirm with the user?** irreversible/one-way door · cost shifted onto another team/ops/maintainer/user · one quality attribute traded for another · a tier/service/event/library boundary crossed · auth/money/data-integrity/breaking-change/High-or-Medium-risk path · verdict UNCLEAR → **STOP and confirm by asking the user directly BEFORE the verdict**. - **MANDATORY** A MATERIAL trade-off with no user confirmation can NEVER be PASS; NEVER bury one as a Low-severity note, NEVER decide it silently, and NEVER let delivery or convergence pressure authorize a one-way door. — why: an un-walked-back one-way door is the user's call to make, not the reviewer's. - **MANDATORY — non-asking contexts escalate BY HANDOFF, never by silence.** ask the user directly reaches only the main interactive agent: a sub-agent cannot ask the user, and a terminal/verdict-only mode asks nothing by design. There the duty is REDIRECTED, not waived — still name the trade-off, still decide materiality, record `confirmed? = NO — cannot ask from this context`, **state the unconfirmed MATERIAL trade-off in your RETURNED verdict/summary so the CALLER escalates it** (a note only in an on-disk report is not a handoff), and never emit an unqualified PASS. Applies ONLY where the user is genuinely unreachable (spawned sub-agent, terminal validate mode, headless run) — if you CAN ask, you MUST ask. > **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `/.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`. > > Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently. **MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `/.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user. ## Closing Reminders **IMPORTANT MUST ATTENTION Goal:** Enforce quality gates, verify compliance with standards, track quality metrics, and generate audit trails across the development lifecycle. **Protocols in force (concise digest of the SYNC/shared blocks this skill carries):** - **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity. - **Critical Thinking:** Traced `file:line` proof per claim; confidence >80% to act. - **Sequential Thinking:** Multi-step Thought N/M with REVISION/BRANCH/HYPOTHESIS markers, confidence closer. **IMPORTANT MUST ATTENTION** break work into small todo tasks using task tracking BEFORE starting **IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code **IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act) **IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality **[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using task tracking. ## Hookless Prompt Protocol Mirror (Auto-Synced) Source: `.claude/.ck.json` + `.claude/skills/shared/sync-inline-versions.md` (`:full` blocks) + `.claude/scripts/lib/hookless-prompt-protocol.cjs` ## [WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason. **Generic portability boundary:** Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from `shared/sdd-artifact-contract.md`. Read `docs/project-config.json` and `docs/project-reference/docs-index-reference.md`, then open the project reference docs named there. For spec, test-case, behavior-change, public-contract, or `docs/specs/` work, route through the local spec docs named by the docs index: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`, and `workflow-spec-test-code-cycle-reference.md` when specs/tests/code must stay synchronized. If either file or a required reference doc is missing or stale, auto-run `$project-init` (or the narrow lower-level route such as `$project-config`, `$docs-init`, `$scan-all`, or `$scan --target=`) before ordinary project-specific work. Any supported AI tool may execute when this shared context and local docs are available. 1. **DETECT:** If the prompt starts with an explicit slash skill/workflow command, execute it directly. Otherwise match the prompt against the workflow catalog and skill list. 2. **ANALYZE:** Choose the best option: execute directly, invoke a skill, activate a standard workflow, or compose a custom step combination. 3. **AUTO-SELECT:** Pick the best option yourself. Do not ask the user to choose between direct execution, skill, standard workflow, or custom workflow. 4. **ACTIVATE:** For a selected workflow, call `$start-workflow `; for a selected skill, invoke that skill; for a custom workflow, sequence custom steps directly; for direct execution, proceed with the task. 5. **CREATE TASKS:** task tracking for ALL workflow/skill/custom steps before execution when the selected path has multiple steps. 6. **PARALLELIZE:** Before executing the task list, tag each task `PAR` (independent inputs + write set disjoint from every other `PAR` task) or `SEQ` (name the blocking dependency), group `PAR` tasks into waves, declare the wave plan, and spawn each wave's sub-agents in ONE message — all-return barrier per wave, fan-out one level deep unless a sub-agent's own definition authorizes further fan-out. Sequential-by-default is a defect when tasks are independent; do not parallelize shared write targets, output-consuming tasks, trivial single-file work, ordering a skill or workflow explicitly fixes, or user-approval gates. 7. **EXECUTE:** Advance per the **Workflow Step Advancement & Parallel Phases** rule in your context instructions — model-driven; a sub-agent completion advances a step identically to an inline call; a parallel-phase group is an all-return barrier (advance only after ALL members return, never serialize it) ## Shared AI-SDD Protocol Markers Source: `.claude/skills/shared/sync-inline-versions.md` ## SYNC:ai-sdd-artifact-contract > **AI-SDD Artifact Contract** — Shared spec-driven development rules stay portable and source-owned. > > 1. Keep reusable AI-SDD principles in `.claude`; put repository-specific paths, commands, owners, products, and formats in project config/reference docs. > 2. Preserve cycle: `spec -> plan -> tasks -> implement -> verify -> update spec/docs`. > 3. Trace every requirement or invariant through decision, task, TC/test, source evidence, and docs/spec update. > 4. Treat code-to-spec extraction as reference-only until accepted by the canonical spec owner. > 5. Any supported AI tool may plan, implement, review, or verify with synced context; using multiple tools is optional. > 6. Update `.claude` source first, then sync generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`. — why: mirrors are generated artifacts; hand-edits are overwritten on the next sync > 7. If `docs/project-config.json`, root instruction files, or a required project-reference doc is missing or stale, auto-run `$project-init` or the narrow lower-level route before ordinary project-specific work. > > **Active reference:** `shared/sdd-artifact-contract.md` in the active skills root. --- ## SYNC:ai-sdd-artifact-contract:reminder - **MANDATORY** Apply `shared/sdd-artifact-contract.md`; keep reusable AI-SDD in `.claude` and local rules in project docs. - **MANDATORY** Code-to-spec extraction is reference-only until canonical acceptance; any supported AI tool may execute with synced context. - **MANDATORY** Update `.claude` source before syncing generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`. - **MANDATORY** Missing or stale project config, root instruction files, or required reference docs route project-specific work through `$project-init` or the narrow setup route automatically. **[TASK-PLANNING] [MANDATORY]** BEFORE executing any workflow or skill step, create/update task tracking for all planned steps, then keep it synchronized as each step starts/completes. ## [LESSON-LEARNED-REMINDER] [BLOCKING] Task Planning & Continuous Improvement — MANDATORY. Do not skip. Break work into small tasks (task tracking) before starting. Add final task: "Analyze AI mistakes & lessons learned". **Extract lessons — ROOT CAUSE ONLY, not symptom fixes:** 1. Name the FAILURE MODE (reasoning/assumption failure), not symptom — "assumed API existed without reading source" not "used wrong enum value". 2. Generality test: does this failure mode apply to ≥3 contexts/codebases? If not, abstract one level up. 3. Write as a universal rule — strip project-specific names/paths/classes. Useful on any codebase. 4. Consolidate: multiple mistakes sharing one failure mode → ONE lesson. 5. **Recurrence gate:** "Would this recur in future session WITHOUT this reminder?" — No → skip `$learn`. 6. **Auto-fix gate:** "Could `$code-review`/`$code-simplifier`/`$security-review`/`$lint` catch this?" — Yes → improve review skill instead. 7. BOTH gates pass → ask user to run `$learn`. **[CRITICAL-THINKING-MINDSET]** Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. **Anti-hallucination principle:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. **AI Attention principle (Primacy-Recency):** Put the 3 most critical rules at both top and bottom of long prompts/protocols so instruction adherence survives long context windows. **Goal-driven execution:** Define success criteria first, loop until verified, and stop only when observable checks pass. **Tests verify intent:** Tests must protect business rules/invariants and fail when the protected intent breaks, not only mirror current behavior. ## Common AI Mistake Prevention (System Lessons) - **Re-read files after context compaction.** Edit requires prior Read in same context; compaction wipes read state. Re-read before editing. - **Grep for old terms after bulk replacements.** AI over-trusts find/replace completeness. Grep full repo after bulk edits for missed refs in docs/configs/catalogs. - **Check downstream references before deleting.** Deletions cascade doc/code staleness. Map referencing files before removal. - **After memory loss, check existing state before creating new.** Compaction wipes prior-work memory. Query current state to resume — never blindly duplicate. - **Verify AI-generated content against actual code.** AI hallucinates APIs, class names, method signatures. Grep to confirm existence before documenting/referencing. - **Trace full dependency chain after edits.** Changing a definition misses downstream consumers. Trace the full chain. - **When renaming, grep ALL consumer file types.** Some file types silently ignore missing refs (no compile error). Search code, templates, configs, generated files. - **Trace ALL code paths when verifying correctness.** Code existing ≠ code executing. Trace early exits, error branches, conditional skips — not just happy path. - **Update docs that embed canonical data when source changes.** Docs inlining derived data (workflows, schemas, configs) go stale silently. Update all embedding docs alongside source. - **Verify sub-agent results after context recovery.** Background agents may finish while parent compacted — grep-verify output, don't trust assumed completion. - **Cross-check full target list against sub-agent assignments.** Parallel sub-agents by category miss boundary items. Reconcile union of assignments against target list before proceeding. - **Sub-agents inherit knowledge only from their agent .md definition — use custom agent types, not built-in Explore.** Tool adoption = permission + knowledge + enforcement (numbered workflow step). - **Persist sub-agent findings incrementally, not as a final batch.** Long sub-agents hit cutoffs before final write — findings lost. Instruct append-pe …(truncated)