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=<key>, $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.
[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.
[BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends.
[BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason.
[BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Quick Summary
Goal: Review an artifact (PBI, design spec, story, test spec) for completeness and quality so reviewed artifacts are complete, evidence-backed, and ready for handoff without missing assumptions or acceptance gaps.
Summary:
- Purpose: review ONE artifact (PBI · user story set · test spec · design spec) for completeness + quality so it ships evidence-backed and handoff-ready — no missing assumptions, no acceptance gaps. Default stance = SKEPTIC, not presence-checker: sections that exist but hold weak/untestable content are worse than missing ones — they breed false confidence.
- Main steps (in order): (1) Identify type — dispatch on
--type={pbi|story|spec-tests|design}, infer if omitted; (2) Adversarial Mindset — run ALL 6 techniques (steel-man rejected alternatives · stress-test 3 assumptions · AC-testability · pre-mortem · unseen alternatives · contrarian pass) + clear the Anti-Bias Gate before any verdict; (3) Type checklist — score Required + Recommended; (4) M1-M7 gate (BLOCKING, ALL types); (5) Readability checklist; (6) Output per-type template (verdict + Required/Recommended tallies + coverage/AC matrix); (7) Validated-fix + full re-review loop — validate findings → fix → restart full review until clean.
- Type dispatch + verdict: each
--type has its own Required/Recommended checklist and output template — verdict = PASS (all Required + ≥50% Recommended) | WARN (all Required, <50% Recommended) | FAIL (any Required fails).
- M1-M7 gate (ALL types, BLOCKING): any M1-M5 or M7 violation forces NEEDS WORK citing the mandate ID + exact section/line; exempt source identifiers inside evidence carriers (
[Source:], **Evidence**, CoveredBy, legacy IntegrationTest, frontmatter, mermaid) — flag tech leakage only in narrative/AC/scenario prose. — why: carriers are the correct home for class/path/test names; flagging them is a false finding. M7 (business-visibility) is judged on each case's BODY via the demo test, NOT its prose — a tech-free-sounding case about a consumer/sync/handler passes M1 and STILL fails M7. — why: M1 governs vocabulary, M7 governs subject matter; the gap between them is how business specs rot.
- Validated-fix loop: before fixing, invoke
$why-review --validate-findings <report-path> on the review report FIRST (validate-before-fix discipline, at parity with $plan-review) — NEVER edit the artifact to resolve findings before this gate returns CLEAN. Then fix only validated findings, do not confirm-in-place, restart the FULL review (fresh general-purpose sub-agent — artifacts are NOT code), loop until a clean pass — clean review ENDS the loop.
Workflow:
- Identify — What artifact type is being reviewed
- Checklist — Apply type-specific quality criteria
- Verdict — READY or NEEDS WORK with specific items
Key Rules:
- Use type-specific checklists
- Every NEEDS WORK item must be actionable
- Focus on completeness — never block on stylistic preferences
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
First Principle — Easy to Change
The success metric of every coding decision is future change cost.
DRY, SRP, abstraction, design patterns, naming, layering, tests — every
technique exists to serve one goal: making the next change cheaper.
When evaluating code, refactor, test, or abstraction, ask:
does this make next change cheaper or more expensive?
- Reject "best practices" raising change cost (premature abstraction,
speculative generality, leaky indirection, ceremony without payoff).
- Name real enemies in findings: coupling, hidden state, duplicated
knowledge, unclear intent, irreversible decisions exposed too early.
- Simpler design easy to change beats sophisticated design that isn't.
Apply this lens before invoking any specific rule, pattern, or checklist
below — if downstream rule would raise change cost, this principle wins.
Adversarial Review Mindset (NON-NEGOTIABLE)
Default stance: SKEPTIC challenging artifact quality and completeness, not confirming presence of sections.
Presence-quality confusion trap: Artifact with all required sections LOOKS complete. But sections that exist yet contain weak, ambiguous, or untestable content are worse than missing sections — they create false confidence. This section forces quality challenge beyond existence checks.
Adversarial Techniques (apply ALL before concluding)
1. Steel-Man the Alternatives
Before accepting chosen approach in any design artifact: argue FOR strongest rejected alternative as vigorously as possible. Would a senior domain expert seriously consider it? If yes — artifact's dismissal needs stronger justification.
2. Assumption Stress Test
List the 3 biggest assumptions embedded in artifact. For each: "What if this is wrong?" An artifact that breaks when 2 of its 3 core assumptions fail is fragile. Flag unaddressed failure modes.
3. Acceptance Criteria Testability
For each acceptance criterion: "Can a QA engineer write a specific automated test for this — without asking clarifying questions?" If not — AC is ambiguous. Flag it. Vague ACs ("feature works correctly") are NOT acceptance criteria.
4. Pre-Mortem
Assume artifact is implemented exactly as written and feature fails in production within 3 months. Write the most plausible failure scenario. If you can't find one, look harder — every implementation has a failure mode.
5. Unseen Alternatives
Identify 1-2 approaches NOT mentioned in artifact. Genuinely not considered, or considered and excluded without documented reasoning? Missing alternatives without exclusion reasoning = incomplete analysis.
6. Contrarian Pass
Before writing any verdict, generate at least 2 sentences arguing the OPPOSITE conclusion. Then decide which argument is stronger based on evidence.
Forbidden Patterns
- "Required sections present" → Presence ≠ quality. What's IN them?
- "Acceptance criteria are defined" → Are they TESTABLE? Name the automated test for each.
- "Scope is well-defined" → What is explicitly OUT of scope? If nothing is out of scope, the scope is undefined.
- "Alternatives were considered" → Were they real alternatives, or strawmen set up to lose?
- "Looks complete" → What specific failure mode is NOT addressed?
Anti-Bias Gate (MANDATORY before finalizing verdict)
If any box is unchecked → adversarial review incomplete. Go back.
Type-Specific Checklists (--type dispatch)
Select the checklist + output template by artifact type. Pass --type={pbi|story|spec-tests|design} to force a type; if omitted, infer from the artifact (Phase 1 "Identify"). Each type scores Required (all must pass) + Recommended (≥50% should pass) → verdict PASS (all Required + ≥50% Recommended) | WARN (all Required, <50% Recommended) | FAIL (any Required fails).
--type |
Artifact |
Output template |
pbi |
Product Backlog Item |
PBI Review Result |
story |
User story set |
Story Review Result (+ AC Coverage Matrix) |
spec-tests |
Test specification |
Test Spec Review Result (+ Coverage Matrix) |
design |
Design spec |
Artifact Review |
PBI Review (--type=pbi)
| # |
Check |
Presence |
Quality Depth |
| 1 |
Problem statement is clear — the problem being solved is described in concrete terms |
Is a problem statement present? Is it 2+ sentences? |
Is the problem scoped correctly? Could it be framed differently to lead to a different (simpler) solution? Are symptoms confused with root cause? |
| 2 |
Acceptance criteria are testable and measurable — each AC can be verified by a test |
Are ACs present? Do they use measurable language? |
Can a QA engineer write an automated test for EACH AC without clarification? Are they specific enough to catch regressions? Vague ACs ("feature works correctly") are not acceptance criteria. |
| 3 |
Scope is well-defined (what's in and out) — both in-scope and out-of-scope items are explicitly listed |
Is an in/out scope list present? Does it have both sides? |
Are out-of-scope items specific enough to prevent scope creep? Is anything ambiguously in/out? A scope that says nothing is out of scope is an undefined scope. |
| 4 |
Dependencies are identified — all external dependencies the PBI relies on are listed |
Is a dependencies section present? Does it list items? |
Are ALL dependencies listed (technical, data, service, team)? Are "can-parallel" items truly safe to parallelize, or do they share a shared resource? |
| 5 |
Business value is articulated — the why behind the PBI is stated in terms of user or business outcome |
Is business value described? |
Is the value quantified or just stated? Does it connect to a user outcome, not just a feature delivery? "Users can now do X" is better than "we implemented feature Y". |
| 6 |
Priority is assigned — the PBI has an explicit priority level |
Is a priority level assigned? |
Is priority justified with data (RICE/MoSCoW), or arbitrary? Is it consistent with other PBIs in the same sprint? A PBI that is "high priority" without justification is unranked. |
User Story Review (--type=story)
| # |
Check |
Presence |
Quality Depth |
| 1 |
Follows GIVEN/WHEN/THEN format — the story uses the structured BDD format |
Are all three parts (GIVEN, WHEN, THEN) present? |
Are all 3 parts present AND meaningful? Or is GIVEN trivial ("Given a user exists")? A GIVEN that describes no precondition adds no value. |
| 2 |
Is independent (not dependent on other stories) — the story can be implemented without requiring another story first |
Is independence stated or inferable? |
Would descoping other stories prevent this story from being implemented? Implicit dependencies are as blocking as explicit ones. |
| 3 |
Is estimable (team can size it) — the team has enough information to assign story points |
Is the story sized or estimable based on content? |
Does the team have enough info to estimate? Is "can't estimate" a sign of missing AC? If it can't be sized, it's not ready for sprint. |
| 4 |
Is small enough for one sprint — the story fits within a single sprint's capacity |
Is the story sized at ≤8 story points or scoped to one sprint? |
Could this be split further? Stories >8SP should always be split. A story that "could fit" in a sprint but requires multiple sub-systems is likely too large. |
| 5 |
Has acceptance criteria — the story defines measurable conditions for completion |
Are acceptance criteria present? |
Are criteria testable? Would they catch a bug if the feature works in 9/10 cases? ACs that only describe the happy path are incomplete. |
Design Spec Review (--type=design)
| # |
Check |
Presence |
Quality Depth |
| 1 |
All component states covered (default, hover, active, disabled, error, loading) — spec defines visual behavior for all interaction states |
Are all 6 states defined? |
Are edge-case states (error, loading) as fully designed as the default state, or sketched? An undesigned error state will be improvised in implementation. |
| 2 |
Design tokens specified (colors, spacing, typography) — specific token values are called out, not ad-hoc values |
Are token references present instead of raw values? |
Are tokens from the project's token system, or are new values introduced? New values outside the token system break design consistency silently. |
| 3 |
Responsive behavior defined — how the component adapts across breakpoints is documented |
Are breakpoint behaviors defined? |
Are ALL breakpoints covered, or only desktop and mobile? Tablet-specific layouts are the most frequently omitted. Are content truncation / overflow behaviors specified? |
| 4 |
Accessibility requirements noted — WCAG-relevant requirements (color contrast, keyboard nav, ARIA) are documented |
Are accessibility notes present? |
Are requirements specific (WCAG level, contrast ratio) or vague ("should be accessible")? Vague accessibility notes produce non-compliant implementations. Is keyboard navigation flow defined? |
| 5 |
Interaction patterns documented — animations, transitions, and user interaction flows are specified |
Are interaction behaviors described? |
Are timing and easing values specified? Is behavior defined for both forward and reverse interactions (e.g., open AND close)? Unspecified interactions are implemented inconsistently. |
| 6 |
Linked from the Feature Spec — the design-spec path is recorded in the governing Feature Spec frontmatter design_spec: key so the spec stays the navigable hub |
Is the design-spec path present in the Feature Spec frontmatter design_spec: (or mockup:) key? |
Does the recorded path resolve to THIS design-spec, and does the design-spec deepen the spec's tech-agnostic §6 interaction surface (same UX-role view names / observable states) rather than diverge from it? An unlinked design-spec is an orphan — FAIL. Contract: SYNC:ui-intent-layer (inlined in this skill). |
UI/UX Design Principles Pass — --type=design ONLY (9 dimensions)
Scope gate: this pass applies to --type=design and to NOTHING else. --type=pbi, --type=story, and --type=spec-tests are UNAFFECTED — their checklists, tallies, and verdicts are unchanged. A design artifact for a feature with no user-facing surface skips the whole pass with the reason stated.
The 40 clauses of SYNC:ui-ux-design-principles (full body inlined below in this skill) bind the design-spec path in the REVIEW role: each clause is a fail-condition against the ARTIFACT — does the spec SPECIFY the decision this clause demands, at a depth an implementer could not get wrong? The missing specification is the finding; the reviewer names the gap, never supplies the value.
Run NINE focused passes over the artifact — one dimension at a time, never a simultaneous sweep (a simultaneous sweep degenerates into the presence-checking this skill's Adversarial Review Mindset already forbids). Answer each Think: prompt from first principles before looking for the gap.
Every finding: UI-<clause> + file:line (artifact section + line) + severity per SYNC:severity-rubric already in force (Critical/High/Medium/Low), folded into the EXISTING verdict machinery — a clause gap that leaves a Required check unmet drives that check to fail (FAIL); a gap that only weakens depth lands as a Recommended miss or an Action Item under NEEDS WORK. No new scale, no new verdict.
| # |
Dimension |
Clauses |
Think: |
| 1 |
Visual Hierarchy & Layout |
UI-1.1-UI-1.5 |
Does the spec name ONE focal element per view, or leave first-read priority to the implementer? Is grouping expressed as whitespace or as nested boxes? Are the empty, loading and error states specified as fully as the populated state, or sketched? |
| 2 |
Typography |
UI-2.1-UI-2.5 |
Does the spec reference a fixed 6-step scale with named families/weights (max 2 families, 3 weights each), or ad-hoc sizes? Are body size (16px web, 17px mobile, never below 14px), measure (45-75 characters), and leading (1.5 body, 1.1-1.2 display) stated or assumed? |
| 3 |
Colour & Contrast |
UI-3.1-UI-3.4 |
Are contrast ratios written as measured numbers (4.5:1 text, 3:1 UI edges) or as the word "accessible"? Does any state carry meaning by colour alone with no icon/label/position pair? Is dark mode specified as its own surface treatment, or implied as an inversion? |
| 4 |
Spacing & Grid |
UI-4.1-UI-4.4 |
Is a single base unit (4px or 8px) declared, with every gap a multiple of it? Is spacing assigned to containers rather than children? Are breakpoints justified by where the layout fails, or copied from device names? |
| 5 |
Interaction & Feedback |
UI-5.1-UI-5.5 |
Is a response under 100ms specified for every action? Are all 5 states plus loading enumerated per component? Is undo offered where the spec calls for a confirmation? Are motion duration/easing (150-250ms, ease-out) and reduced-motion behaviour written down? Is the focus ring's appearance specified rather than removed? |
| 6 |
Navigation & IA |
UI-6.1-UI-6.4 |
Does each specified view answer where-am-I / what's-here / where-next? How many top-level destinations does the IA declare (max 5)? Are labels drawn from user vocabulary or internal naming? Does every state have a URL or a defined back path? |
| 7 |
Forms & Input |
UI-7.1-UI-7.5 |
Does the spec justify each field's existence today? Are labels specified as persistently visible rather than placeholders? Are validation timing (on blur), error placement, and remediation wording defined? Are keyboard type/autocomplete/autocapitalise declared per field? Is data preservation across error, navigation and refresh specified? |
| 8 |
Mobile & Touch |
UI-8.1-UI-8.4 |
Are hit targets specified at >=44x44pt with 8px separation independent of icon size? Where does the spec place primary actions relative to the thumb zone? Is every gesture given a tappable equivalent? Are safe areas and keyboard avoidance addressed? (No touch surface in the artifact → skip with the reason stated.) |
| 9 |
Speed & Perceived Speed |
UI-9.1-UI-9.4 |
Does the spec choose skeleton vs spinner deliberately per surface? Is optimistic update with a VISIBLE rollback specified? Is reserved space defined for every async or media element so nothing shifts? Are offline, timeout and retry specified as designed states rather than left as edge cases? |
No double-counting with Design Spec checks 1-6: check 1 (6 component states) meets UI-5.2/UI-1.5; check 2 (design tokens) meets UI-2.5/UI-4.1/UI-3.2; check 3 (responsive) meets UI-4.4/UI-8.*; check 4 (accessibility) meets UI-3.1/UI-3.3/UI-5.5; check 5 (interaction patterns) meets UI-5.4/UI-5.1. Where they meet, emit ONE finding carrying BOTH citations at the HIGHER severity — never two findings for one gap.
Precedence: the project design-system / SCSS / token docs OUTRANK these clauses — a spec following the project's own scale, unit, breakpoints, or token pairs SATISFIES the clause. A genuine conflict is surfaced to the user with both sides, NEVER resolved silently.
Test Spec Review (--type=spec-tests)
[BLOCKING] Read docs/project-reference/spec-principles.md — use Section 5 (Test Case Registry — TC ID format, priorities, minimum coverage) and Section 6 (Evidence Format) as review criteria in addition to the checklist below.
[BLOCKING] Tech-agnostic check: flag framework/product/language/design-pattern names in a TC's behavioral prose as findings (per spec-principles.md §3). Source paths, class names, and test identifiers (e.g. {File}::{Method}) are CORRECT in evidence fields (**Evidence**, CoveredBy, legacy IntegrationTest, [Source:]), frontmatter, and Mermaid — never flag those.
[BLOCKING] Business-oriented TCs / one-to-many cardinality: Each TC must read as a business / user-story acceptance scenario, not a per-class/per-method technical unit. Flag any TC that appears split or narrowed just to mirror code structure (e.g. one TC per handler/component when the user-observable behavior is the same) — that breaks M1/M5 and the business orientation. One business TC is expected to be covered by many annotation-tagged tests across components/services; that one-to-many shape is correct and is NEVER a finding. Canonical contract: .claude/skills/shared/tc-format.md → TC ↔ Test Code Cardinality.
Required (all must pass)
| # |
Check |
Presence |
Quality Depth |
| 1 |
TC ID format — All TCs follow TC-{FEATURE}-{NNN} format |
Do all TCs use the TC-{FEATURE}-{NNN} pattern? |
Are IDs unique per TC? Does the FEATURE code match the actual feature? |
| 2 |
Story coverage — Every user story has at least one corresponding TC |
Does every story ID appear in at least one TC? |
Does each TC actually test the story behavior, or does it just reference the story ID in a comment? |
| 3 |
AC coverage — Every acceptance criterion has a test case |
Is every AC traceable to at least one TC? |
Does each AC have a TC that would FAIL if the AC is violated? Single-test-per-AC misses edge cases. |
| 4 |
Happy path — Each story has at least one happy path TC |
Is a happy path TC present per story? |
Does the happy path TC verify the full end-to-end scenario, or just a happy-path stub? |
| 5 |
Error path — Each story has at least one error/failure TC |
Is an error/failure TC present per story? |
Does the error TC verify the exact error response (code + message), not just that an error occurred? |
| 6 |
No duplicate TCs — No two TC IDs describe the same business scenario |
Are all TC IDs unique with distinct business scenarios? |
Flag near-duplicate TCs (same scenario, trivially different input). NOTE: this is about duplicate TCs — multiple test methods sharing one TC is the expected one-to-many shape, NEVER a duplicate. |
| 7 |
Testable assertions — Each TC has clear expected result (not vague "should work") |
Does each TC have a specific expected result? |
Is each assertion specific enough to catch regressions? Would it pass if the return value is wrong? |
| 8 |
Business intent / invariant guarded — Each TC names the rule it protects |
Does every meaningful TC include Business Intent / Invariant Guarded? |
Would the TC fail if that business rule/invariant breaks, or does it only mirror implementation details? |
| 9 |
Authorization TCs — At least 1 TC per story verifying unauthorized access is rejected |
Is an authorization TC present per story? |
Does the authorization TC test a realistic access scenario, not just "wrong role → 403 without body check"? |
| 10 |
TC format completeness — Every TC has Related Behaviors anchor table and CoveredBy: field |
Does every TC include a Related Behaviors anchor table and CoveredBy: field? Legacy IntegrationTest: is migration input only. |
For Tested-status TCs, is CoveredBy: populated with ≥1 covering test link {TestFile}::{MethodName}, a test-filter expression, or an approved manual-QC marker — not Untested? A TC may list several covering tests; never require exactly one. |
| 1 |
|
|
|
…(truncated)
1---2name: artifact-review3description: "[Code Quality] Use when you need to review artifact quality (PBI, user story, test spec, design spec) before handoff. Supports --type={pbi|story|spec-tests|design}."4---56> Codex compatibility note:7>8> - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references.9> - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.10> - User-question prompts mean to ask the user directly in Codex.11> - Ignore Claude-specific mode-switch instructions when they appear.12> - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.13> - 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.14> - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.15> - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.16> - If a required step/tool cannot run in this environment, stop and ask the user before adapting.1718<!-- CODEX:PROJECT-REFERENCE-LOADING:START -->1920## Codex Project-Reference Loading (No Hooks)2122Codex uses static project-reference loading instead of runtime-injected project docs.23When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.2425**Always read:**2627- `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings)28- `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog)29- `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns)3031**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=<key>`, `$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.3233**Situation-based docs:**3435- Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md`36- Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md`37- Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md`38- Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`39- Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above40- Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/`41- Integration test implementation/review: `integration-test-reference.md`42- E2E test implementation/review: `e2e-test-reference.md`43- Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files4445Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task.4647<!-- CODEX:PROJECT-REFERENCE-LOADING:END -->4849<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->5051> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.52> **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends.53> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.54> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.5556<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->5758## Quick Summary5960**Goal:** Review an artifact (PBI, design spec, story, test spec) for completeness and quality so reviewed artifacts are complete, evidence-backed, and ready for handoff without missing assumptions or acceptance gaps.6162**Summary:**6364- **Purpose:** review ONE artifact (PBI · user story set · test spec · design spec) for completeness + quality so it ships evidence-backed and handoff-ready — no missing assumptions, no acceptance gaps. Default stance = SKEPTIC, not presence-checker: sections that exist but hold weak/untestable content are worse than missing ones — they breed false confidence.65- **Main steps (in order):** (1) **Identify** type — dispatch on `--type={pbi|story|spec-tests|design}`, infer if omitted; (2) **Adversarial Mindset** — run ALL 6 techniques (steel-man rejected alternatives · stress-test 3 assumptions · AC-testability · pre-mortem · unseen alternatives · contrarian pass) + clear the Anti-Bias Gate before any verdict; (3) **Type checklist** — score Required + Recommended; (4) **M1-M7 gate** (BLOCKING, ALL types); (5) **Readability checklist**; (6) **Output** per-type template (verdict + Required/Recommended tallies + coverage/AC matrix); (7) **Validated-fix + full re-review loop** — validate findings → fix → restart full review until clean.66- **Type dispatch + verdict:** each `--type` has its own Required/Recommended checklist and output template — verdict = PASS (all Required + ≥50% Recommended) | WARN (all Required, <50% Recommended) | FAIL (any Required fails).67- **M1-M7 gate (ALL types, BLOCKING):** any **M1-M5 or M7** violation forces NEEDS WORK citing the mandate ID + exact section/line; exempt source identifiers inside evidence carriers (`[Source:]`, `**Evidence**`, `CoveredBy`, legacy `IntegrationTest`, frontmatter, mermaid) — flag tech leakage only in narrative/AC/scenario prose. — why: carriers are the correct home for class/path/test names; flagging them is a false finding. **M7 (business-visibility) is judged on each case's BODY via the demo test, NOT its prose** — a tech-free-sounding case about a consumer/sync/handler passes M1 and STILL fails M7. — why: M1 governs vocabulary, M7 governs subject matter; the gap between them is how business specs rot.68- **Validated-fix loop:** before fixing, invoke `$why-review --validate-findings <report-path>` on the review report FIRST (validate-before-fix discipline, at parity with `$plan-review`) — NEVER edit the artifact to resolve findings before this gate returns CLEAN. Then fix only validated findings, do not confirm-in-place, restart the FULL review (fresh `general-purpose` sub-agent — artifacts are NOT code), loop until a clean pass — clean review ENDS the loop.6970**Workflow:**71721. **Identify** — What artifact type is being reviewed732. **Checklist** — Apply type-specific quality criteria743. **Verdict** — READY or NEEDS WORK with specific items7576**Key Rules:**7778- Use type-specific checklists79- Every NEEDS WORK item must be actionable80- Focus on completeness — never block on stylistic preferences8182**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**8384## First Principle — Easy to Change8586> **The success metric of every coding decision is _future change cost_.**87> DRY, SRP, abstraction, design patterns, naming, layering, tests — every88> technique exists to serve one goal: **making the next change cheaper**.8990When evaluating code, refactor, test, or abstraction, ask:91**does this make next change cheaper or more expensive?**9293- Reject "best practices" raising change cost (premature abstraction,94 speculative generality, leaky indirection, ceremony without payoff).95- Name real enemies in findings: **coupling, hidden state, duplicated96 knowledge, unclear intent, irreversible decisions exposed too early**.97- Simpler design easy to change beats sophisticated design that isn't.9899Apply this lens **before** invoking any specific rule, pattern, or checklist100below — if downstream rule would raise change cost, this principle wins.101102---103104## Adversarial Review Mindset (NON-NEGOTIABLE)105106**Default stance: SKEPTIC challenging artifact quality and completeness, not confirming presence of sections.**107108> **Presence-quality confusion trap:** Artifact with all required sections LOOKS complete. But sections that exist yet contain weak, ambiguous, or untestable content are worse than missing sections — they create false confidence. This section forces quality challenge beyond existence checks.109110### Adversarial Techniques (apply ALL before concluding)111112**1. Steel-Man the Alternatives**113Before accepting chosen approach in any design artifact: argue FOR strongest rejected alternative as vigorously as possible. Would a senior domain expert seriously consider it? If yes — artifact's dismissal needs stronger justification.114115**2. Assumption Stress Test**116List the 3 biggest assumptions embedded in artifact. For each: "What if this is wrong?" An artifact that breaks when 2 of its 3 core assumptions fail is fragile. Flag unaddressed failure modes.117118**3. Acceptance Criteria Testability**119For each acceptance criterion: "Can a QA engineer write a specific automated test for this — without asking clarifying questions?" If not — AC is ambiguous. Flag it. Vague ACs ("feature works correctly") are NOT acceptance criteria.120121**4. Pre-Mortem**122Assume artifact is implemented exactly as written and feature fails in production within 3 months. Write the most plausible failure scenario. If you can't find one, look harder — every implementation has a failure mode.123124**5. Unseen Alternatives**125Identify 1-2 approaches NOT mentioned in artifact. Genuinely not considered, or considered and excluded without documented reasoning? Missing alternatives without exclusion reasoning = incomplete analysis.126127**6. Contrarian Pass**128Before writing any verdict, generate at least 2 sentences arguing the OPPOSITE conclusion. Then decide which argument is stronger based on evidence.129130### Forbidden Patterns131132- **"Required sections present"** → Presence ≠ quality. What's IN them?133- **"Acceptance criteria are defined"** → Are they TESTABLE? Name the automated test for each.134- **"Scope is well-defined"** → What is explicitly OUT of scope? If nothing is out of scope, the scope is undefined.135- **"Alternatives were considered"** → Were they real alternatives, or strawmen set up to lose?136- **"Looks complete"** → What specific failure mode is NOT addressed?137138### Anti-Bias Gate (MANDATORY before finalizing verdict)139140- [ ] Steel-manned at least one rejected alternative141- [ ] Identified 3 hidden assumptions and stress-tested them142- [ ] Verified each AC is unambiguously testable (can write automated test without clarification)143- [ ] Ran pre-mortem (one concrete production failure scenario)144- [ ] Identified at least 1 unexamined alternative (not in artifact)145- [ ] Generated at least 2 sentences arguing the opposite verdict146147If any box is unchecked → adversarial review incomplete. Go back.148149## Type-Specific Checklists (`--type` dispatch)150151Select the checklist + output template by artifact type. Pass `--type={pbi|story|spec-tests|design}` to force a type; if omitted, infer from the artifact (Phase 1 "Identify"). Each type scores **Required (all must pass)** + **Recommended (≥50% should pass)** → verdict **PASS** (all Required + ≥50% Recommended) | **WARN** (all Required, <50% Recommended) | **FAIL** (any Required fails).152153| `--type` | Artifact | Output template |154| ------------ | -------------------- | ------------------------------------------- |155| `pbi` | Product Backlog Item | PBI Review Result |156| `story` | User story set | Story Review Result (+ AC Coverage Matrix) |157| `spec-tests` | Test specification | Test Spec Review Result (+ Coverage Matrix) |158| `design` | Design spec | Artifact Review |159160### PBI Review (`--type=pbi`)161162| # | Check | Presence | Quality Depth |163| --- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |164| 1 | **Problem statement is clear** — the problem being solved is described in concrete terms | Is a problem statement present? Is it 2+ sentences? | Is the problem scoped correctly? Could it be framed differently to lead to a different (simpler) solution? Are symptoms confused with root cause? |165| 2 | **Acceptance criteria are testable and measurable** — each AC can be verified by a test | Are ACs present? Do they use measurable language? | Can a QA engineer write an automated test for EACH AC without clarification? Are they specific enough to catch regressions? Vague ACs ("feature works correctly") are not acceptance criteria. |166| 3 | **Scope is well-defined (what's in and out)** — both in-scope and out-of-scope items are explicitly listed | Is an in/out scope list present? Does it have both sides? | Are out-of-scope items specific enough to prevent scope creep? Is anything ambiguously in/out? A scope that says nothing is out of scope is an undefined scope. |167| 4 | **Dependencies are identified** — all external dependencies the PBI relies on are listed | Is a dependencies section present? Does it list items? | Are ALL dependencies listed (technical, data, service, team)? Are "can-parallel" items truly safe to parallelize, or do they share a shared resource? |168| 5 | **Business value is articulated** — the why behind the PBI is stated in terms of user or business outcome | Is business value described? | Is the value quantified or just stated? Does it connect to a user outcome, not just a feature delivery? "Users can now do X" is better than "we implemented feature Y". |169| 6 | **Priority is assigned** — the PBI has an explicit priority level | Is a priority level assigned? | Is priority justified with data (RICE/MoSCoW), or arbitrary? Is it consistent with other PBIs in the same sprint? A PBI that is "high priority" without justification is unranked. |170171### User Story Review (`--type=story`)172173| # | Check | Presence | Quality Depth |174| --- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |175| 1 | **Follows GIVEN/WHEN/THEN format** — the story uses the structured BDD format | Are all three parts (GIVEN, WHEN, THEN) present? | Are all 3 parts present AND meaningful? Or is GIVEN trivial ("Given a user exists")? A GIVEN that describes no precondition adds no value. |176| 2 | **Is independent (not dependent on other stories)** — the story can be implemented without requiring another story first | Is independence stated or inferable? | Would descoping other stories prevent this story from being implemented? Implicit dependencies are as blocking as explicit ones. |177| 3 | **Is estimable (team can size it)** — the team has enough information to assign story points | Is the story sized or estimable based on content? | Does the team have enough info to estimate? Is "can't estimate" a sign of missing AC? If it can't be sized, it's not ready for sprint. |178| 4 | **Is small enough for one sprint** — the story fits within a single sprint's capacity | Is the story sized at ≤8 story points or scoped to one sprint? | Could this be split further? Stories >8SP should always be split. A story that "could fit" in a sprint but requires multiple sub-systems is likely too large. |179| 5 | **Has acceptance criteria** — the story defines measurable conditions for completion | Are acceptance criteria present? | Are criteria testable? Would they catch a bug if the feature works in 9/10 cases? ACs that only describe the happy path are incomplete. |180181### Design Spec Review (`--type=design`)182183| # | Check | Presence | Quality Depth |184| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |185| 1 | **All component states covered (default, hover, active, disabled, error, loading)** — spec defines visual behavior for all interaction states | Are all 6 states defined? | Are edge-case states (error, loading) as fully designed as the default state, or sketched? An undesigned error state will be improvised in implementation. |186| 2 | **Design tokens specified (colors, spacing, typography)** — specific token values are called out, not ad-hoc values | Are token references present instead of raw values? | Are tokens from the project's token system, or are new values introduced? New values outside the token system break design consistency silently. |187| 3 | **Responsive behavior defined** — how the component adapts across breakpoints is documented | Are breakpoint behaviors defined? | Are ALL breakpoints covered, or only desktop and mobile? Tablet-specific layouts are the most frequently omitted. Are content truncation / overflow behaviors specified? |188| 4 | **Accessibility requirements noted** — WCAG-relevant requirements (color contrast, keyboard nav, ARIA) are documented | Are accessibility notes present? | Are requirements specific (WCAG level, contrast ratio) or vague ("should be accessible")? Vague accessibility notes produce non-compliant implementations. Is keyboard navigation flow defined? |189| 5 | **Interaction patterns documented** — animations, transitions, and user interaction flows are specified | Are interaction behaviors described? | Are timing and easing values specified? Is behavior defined for both forward and reverse interactions (e.g., open AND close)? Unspecified interactions are implemented inconsistently. |190| 6 | **Linked from the Feature Spec** — the design-spec path is recorded in the governing Feature Spec frontmatter `design_spec:` key so the spec stays the navigable hub | Is the design-spec path present in the Feature Spec frontmatter `design_spec:` (or `mockup:`) key? | Does the recorded path resolve to THIS design-spec, and does the design-spec deepen the spec's tech-agnostic §6 interaction surface (same UX-role view names / observable states) rather than diverge from it? An unlinked design-spec is an orphan — FAIL. Contract: `SYNC:ui-intent-layer` (inlined in this skill). |191192#### UI/UX Design Principles Pass — `--type=design` ONLY (9 dimensions)193194> **Scope gate:** this pass applies to `--type=design` and to NOTHING else. `--type=pbi`, `--type=story`, and `--type=spec-tests` are UNAFFECTED — their checklists, tallies, and verdicts are unchanged. A design artifact for a feature with no user-facing surface skips the whole pass with the reason stated.195196The 40 clauses of `SYNC:ui-ux-design-principles` (full body inlined below in this skill) bind the design-spec path in the **REVIEW** role: each clause is a fail-condition against the ARTIFACT — _does the spec SPECIFY the decision this clause demands, at a depth an implementer could not get wrong?_ The missing specification is the finding; the reviewer names the gap, never supplies the value.197198Run **NINE focused passes over the artifact — one dimension at a time**, never a simultaneous sweep (a simultaneous sweep degenerates into the presence-checking this skill's Adversarial Review Mindset already forbids). Answer each `Think:` prompt from first principles before looking for the gap.199200**Every finding:** `UI-<clause>` + `file:line` (artifact section + line) + severity per `SYNC:severity-rubric` already in force (Critical/High/Medium/Low), folded into the EXISTING verdict machinery — a clause gap that leaves a Required check unmet drives that check to fail (**FAIL**); a gap that only weakens depth lands as a Recommended miss or an Action Item under **NEEDS WORK**. No new scale, no new verdict.201202| # | Dimension | Clauses | `Think:` |203| --- | ------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |204| 1 | Visual Hierarchy & Layout | `UI-1.1`-`UI-1.5` | Does the spec name ONE focal element per view, or leave first-read priority to the implementer? Is grouping expressed as whitespace or as nested boxes? Are the empty, loading and error states specified as fully as the populated state, or sketched? |205| 2 | Typography | `UI-2.1`-`UI-2.5` | Does the spec reference a fixed 6-step scale with named families/weights (max 2 families, 3 weights each), or ad-hoc sizes? Are body size (16px web, 17px mobile, never below 14px), measure (45-75 characters), and leading (1.5 body, 1.1-1.2 display) stated or assumed? |206| 3 | Colour & Contrast | `UI-3.1`-`UI-3.4` | Are contrast ratios written as measured numbers (4.5:1 text, 3:1 UI edges) or as the word "accessible"? Does any state carry meaning by colour alone with no icon/label/position pair? Is dark mode specified as its own surface treatment, or implied as an inversion? |207| 4 | Spacing & Grid | `UI-4.1`-`UI-4.4` | Is a single base unit (4px or 8px) declared, with every gap a multiple of it? Is spacing assigned to containers rather than children? Are breakpoints justified by where the layout fails, or copied from device names? |208| 5 | Interaction & Feedback | `UI-5.1`-`UI-5.5` | Is a response under 100ms specified for every action? Are all 5 states plus loading enumerated per component? Is undo offered where the spec calls for a confirmation? Are motion duration/easing (150-250ms, ease-out) and reduced-motion behaviour written down? Is the focus ring's appearance specified rather than removed? |209| 6 | Navigation & IA | `UI-6.1`-`UI-6.4` | Does each specified view answer where-am-I / what's-here / where-next? How many top-level destinations does the IA declare (max 5)? Are labels drawn from user vocabulary or internal naming? Does every state have a URL or a defined back path? |210| 7 | Forms & Input | `UI-7.1`-`UI-7.5` | Does the spec justify each field's existence today? Are labels specified as persistently visible rather than placeholders? Are validation timing (on blur), error placement, and remediation wording defined? Are keyboard type/autocomplete/autocapitalise declared per field? Is data preservation across error, navigation and refresh specified? |211| 8 | Mobile & Touch | `UI-8.1`-`UI-8.4` | Are hit targets specified at >=44x44pt with 8px separation independent of icon size? Where does the spec place primary actions relative to the thumb zone? Is every gesture given a tappable equivalent? Are safe areas and keyboard avoidance addressed? _(No touch surface in the artifact → skip with the reason stated.)_ |212| 9 | Speed & Perceived Speed | `UI-9.1`-`UI-9.4` | Does the spec choose skeleton vs spinner deliberately per surface? Is optimistic update with a VISIBLE rollback specified? Is reserved space defined for every async or media element so nothing shifts? Are offline, timeout and retry specified as designed states rather than left as edge cases? |213214**No double-counting** with Design Spec checks 1-6: check 1 (6 component states) meets `UI-5.2`/`UI-1.5`; check 2 (design tokens) meets `UI-2.5`/`UI-4.1`/`UI-3.2`; check 3 (responsive) meets `UI-4.4`/`UI-8.*`; check 4 (accessibility) meets `UI-3.1`/`UI-3.3`/`UI-5.5`; check 5 (interaction patterns) meets `UI-5.4`/`UI-5.1`. Where they meet, emit ONE finding carrying BOTH citations at the HIGHER severity — never two findings for one gap.215216**Precedence:** the project design-system / SCSS / token docs **OUTRANK** these clauses — a spec following the project's own scale, unit, breakpoints, or token pairs SATISFIES the clause. A genuine conflict is surfaced to the user with both sides, NEVER resolved silently.217218### Test Spec Review (`--type=spec-tests`)219220> **[BLOCKING] Read** `docs/project-reference/spec-principles.md` — use Section 5 (Test Case Registry — TC ID format, priorities, minimum coverage) and Section 6 (Evidence Format) as review criteria in addition to the checklist below.221> **[BLOCKING] Tech-agnostic check:** flag framework/product/language/design-pattern names in a TC's behavioral prose as findings (per `spec-principles.md` §3). Source paths, class names, and test identifiers (e.g. `{File}::{Method}`) are CORRECT in evidence fields (`**Evidence**`, `CoveredBy`, legacy `IntegrationTest`, `[Source:]`), frontmatter, and Mermaid — never flag those.222> **[BLOCKING] Business-oriented TCs / one-to-many cardinality:** Each TC must read as a **business / user-story acceptance scenario**, not a per-class/per-method technical unit. **Flag** any TC that appears split or narrowed just to mirror code structure (e.g. one TC per handler/component when the user-observable behavior is the same) — that breaks M1/M5 and the business orientation. One business TC is expected to be covered by **many** annotation-tagged tests across components/services; that one-to-many shape is correct and is NEVER a finding. Canonical contract: `.claude/skills/shared/tc-format.md` → TC ↔ Test Code Cardinality.223224#### Required (all must pass)225226| # | Check | Presence | Quality Depth |227| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |228| 1 | **TC ID format** — All TCs follow `TC-{FEATURE}-{NNN}` format | Do all TCs use the `TC-{FEATURE}-{NNN}` pattern? | Are IDs unique per TC? Does the FEATURE code match the actual feature? |229| 2 | **Story coverage** — Every user story has at least one corresponding TC | Does every story ID appear in at least one TC? | Does each TC actually test the story behavior, or does it just reference the story ID in a comment? |230| 3 | **AC coverage** — Every acceptance criterion has a test case | Is every AC traceable to at least one TC? | Does each AC have a TC that would FAIL if the AC is violated? Single-test-per-AC misses edge cases. |231| 4 | **Happy path** — Each story has at least one happy path TC | Is a happy path TC present per story? | Does the happy path TC verify the full end-to-end scenario, or just a happy-path stub? |232| 5 | **Error path** — Each story has at least one error/failure TC | Is an error/failure TC present per story? | Does the error TC verify the exact error response (code + message), not just that an error occurred? |233| 6 | **No duplicate TCs** — No two TC IDs describe the same business scenario | Are all TC IDs unique with distinct **business** scenarios? | Flag near-duplicate TCs (same scenario, trivially different input). NOTE: this is about duplicate _TCs_ — multiple _test methods_ sharing one TC is the expected one-to-many shape, NEVER a duplicate. |234| 7 | **Testable assertions** — Each TC has clear expected result (not vague "should work") | Does each TC have a specific expected result? | Is each assertion specific enough to catch regressions? Would it pass if the return value is wrong? |235| 8 | **Business intent / invariant guarded** — Each TC names the rule it protects | Does every meaningful TC include `Business Intent / Invariant Guarded`? | Would the TC fail if that business rule/invariant breaks, or does it only mirror implementation details? |236| 9 | **Authorization TCs** — At least 1 TC per story verifying unauthorized access is rejected | Is an authorization TC present per story? | Does the authorization TC test a realistic access scenario, not just "wrong role → 403 without body check"? |237| 10 | **TC format completeness** — Every TC has Related Behaviors anchor table and `CoveredBy:` field | Does every TC include a Related Behaviors anchor table and `CoveredBy:` field? Legacy `IntegrationTest:` is migration input only. | For Tested-status TCs, is `CoveredBy:` populated with **≥1** covering test link `{TestFile}::{MethodName}`, a test-filter expression, or an approved manual-QC marker — not `Untested`? A TC may list several covering tests; never require exactly one. |238| 1239240…(truncated)