cl-reviewer

Folder Structure

project/
├── docs/
│   ├── system/              # The source of truth you review against
│   │   ├── .manifest.md     # Auto-generated doc index
│   │   └── *.md             # System docs
│   ├── research/            # Check for corresponding research
│   ├── proposals/           # What you review (P-NNN-slug.md)
│   ├── reviews/             # Where your reviews go
│   │   ├── proposals/       # Proposal reviews
│   │   │   ├── REVIEW_P-001_v1.md    # Initial review
│   │   │   ├── REVIEW_P-001_v2.md    # Re-review after fixes
│   │   │   ├── VERIFY_P-001.md       # Post-merge verification
│   │   │   └── ...
│   │   ├── audit/           # System audits
│   │   │   ├── AUDIT_2026-02-08.md
│   │   │   └── ...
│   │   └── design/          # Design reviews
│   │       └── DESIGN_REVIEW_2026-02-09.md
│   ├── designs/             # Design files (.pen, DESIGN_PROGRESS.md)
│   ├── specs/               # Generated specs (by cl-implementer)
│   ├── DECISIONS.md          # Architectural decisions + conflict resolutions
│   ├── RESEARCH_LEDGER.md   # Research cycle tracking
│   ├── PROPOSAL_TRACKER.md  # Proposal tracking
│   └── PARKING.md           # Parked findings, gaps, and ideas

Session Start (Run First)

Configuration

Before any other checks, read .clarity-loop.json from the project root. If it exists and has a docsRoot field, use that value as the base path for all documentation directories. If it does not exist, use the default docs/.

Throughout this skill, all path references like docs/system/, docs/research/, docs/proposals/, docs/PARKING.md, etc. should be read relative to the configured root. For example, if docsRoot is clarity-docs, then docs/system/ means clarity-docs/system/, docs/PARKING.md means clarity-docs/PARKING.md, and so on.

Pipeline State Check

Before running any mode, check the pipeline state to orient yourself and the user:

1. Check for stale .pipeline-authorized marker — If docs/system/.pipeline-authorized exists, a previous session may have crashed mid-operation. Read the marker to understand what was happening:

   • operation: merge → a merge was interrupted. Check which proposal was being merged and what changes were already applied.
   • operation: correct → corrections were interrupted. Check the corrections log for what was done.
   • operation: bootstrap → initial doc creation was interrupted. Tell the user: "Found a stale authorization marker from a previous [operation] session. Should I check what was completed and finish, or clean up and start fresh?"

2. Read tracking files to understand current state:

   • docs/PROPOSAL_TRACKER.md — any proposals with status in-review, approved (but not merged), or merging?
   • docs/RESEARCH_LEDGER.md — any active research that might produce proposals?
   • docs/PARKING.md — any parked findings or architectural items?
   • docs/DECISIONS.md — scan the Decision Log for prior decisions related to the proposal or system docs under review. During review, check new proposals against existing decisions — if a proposal contradicts or revisits a prior decision, flag it: "This proposal conflicts with D-NNN which decided [X]. Is this an intentional reversal?"

3. Orient the user — briefly summarize where the pipeline stands:

   • If proposals have in-review status, mention them
   • If proposals have approved status but no merged/verified, suggest merge then verify
   • If the stale marker situation was resolved in step 1, note what happened
   • Any architectural items parked? (from PARKING.md active section)

This orientation should be brief — 2-3 sentences max. Don't dump the full state on the user. Just highlight what's actionable.

Reference file convention: When loading a reference file, read its YAML frontmatter to understand the mode's tier (structured or guided), dependencies, and state files. Follow the file's Workflow section (Tier 1: Structured) or Process section (Tier 2: Guided). Consult the Variables table for the mode's inputs and outputs.

Mode Detection

Determine which mode to run based on the user's request and existing review files:

• Initial review: No previous reviews exist in docs/reviews/proposals/ for this proposal. Run the full review process below.
• Re-review: Previous review files exist (e.g., REVIEW_P-NNN_v1.md). The user has had the AI fix issues from the last review and wants you to verify. Run the re-review process (see "Re-Review Mode" section).
• Merge: The user wants to apply an approved proposal to system docs. The proposal must have an APPROVE or APPROVE WITH CHANGES verdict. Run the merge process (see "Merge Mode" section).
• Fix: The user wants help addressing blocking issues from a review. Run the fix process (see "Fix Mode" section).
• Verify: The user explicitly asks to verify system docs after a proposal has been merged. The proposal should have an APPROVE verdict in its latest review. Run the post-merge verification process (see "Verify Mode" section).
• Audit: The user asks to audit the full system documentation set. No proposal is involved — this is a system-wide health check. Run the audit process (see "Audit Mode" section).
• Correct: The user wants to apply targeted fixes from audit findings, verify issues, spec review results, or user-spotted problems — without going through the full research -> proposal pipeline. Run the correction process (see "Correction Mode" section).
• Sync: The user wants to check whether system doc claims still match the actual codebase. Run the code-doc sync process (see "Sync Mode" section).
• Design review: The user wants to review design artifacts (DESIGN_SYSTEM.md, UI_SCREENS.md, .pen files) against system docs and for internal consistency. Run the design review process (see "Design Review Mode" section).

To detect: check docs/reviews/proposals/ for files matching REVIEW_P-NNN_v*.md. If any exist and the user says "review", default to re-review mode. If the user says "merge", "apply this proposal", "apply to system docs", or "update system docs from proposal", run merge mode. If the user says "fix the proposal", "address the review issues", "fix blocking issues", or asks for help resolving review feedback, run fix mode. If the user says "verify", always run verify mode. If no reviews exist and the user says "verify", warn them that the proposal hasn't been reviewed yet and ask if they want to run an initial review first. If the user says "audit" or asks about overall system doc health/consistency/drift, run audit mode — no proposal argument is needed. If the user says "correct", "fix these", "apply corrections", or references fixing issues from an audit or spec review, run correction mode. If the user says "sync", "check docs against code", "code-doc sync", "are the docs still accurate", or asks about whether docs match the codebase, run sync mode. If the user says "design review", "review the designs", "check the design system", "validate designs", or asks about design artifact quality, run design review mode.

Initial Review

When running an initial review, read references/review-mode.md and follow its process.

Initial review gathers context (proposal, manifest, research doc, proposal tracker), spot-checks ground truth (3-5 Change Manifest items verified against actual target files and codebase), analyzes across seven dimensions (value, internal coherence, external consistency, technical soundness, completeness, spec-readiness, ground truth), checks for cross-proposal conflicts, and produces a review file at docs/reviews/proposals/REVIEW_P-NNN_v1.md with verdict, blocking issues, non-blocking suggestions, consistency map, and risk assessment.

Re-Review Mode

When running a re-review, read references/re-review-mode.md and follow its process.

Re-review verifies that fixes from previous reviews landed correctly and that the fix process didn't introduce new problems or regressions. It builds a cumulative issue ledger from ALL previous reviews and checks every item — not just the last review's issues.

Verify Mode

When running post-merge verification, read references/verify-mode.md and follow its process.

Verify mode runs after a proposal has been approved and the system docs have been updated. It checks that the proposal was applied faithfully, that system docs remain consistent with each other, that no collateral damage occurred during the merge, and that code-related claims in merged sections still match the actual codebase (targeted code alignment check).

Audit Mode

When running a full system audit, read references/audit-mode.md and follow its process.

Audit mode is the most comprehensive and expensive operation in the pipeline. It reads ALL system docs fresh (no manifest), performs eight-dimension analysis including external research to verify technical claims, design completeness checking, checks for goal drift against previous audits, and produces a detailed health report. No proposal is involved — this is a system-wide health check.

Output: docs/reviews/audit/AUDIT_[YYYY-MM-DD].md

Usage: /cl-reviewer audit

Merge Mode

When applying an approved proposal to system docs, read references/merge-mode.md and follow its process.

Merge mode is the bridge between an APPROVE verdict and the verify step. It reads the proposal's Change Manifest, presents a merge plan for user approval, runs pre-apply validation (confirms target files still match proposal assumptions — auto-proceeds on clean, presents impact-assessed report on issues), creates a .pipeline-authorized marker (operation: merge), applies changes to system docs, removes the marker, and auto-triggers verify mode.

The workflow:

1. Verify prerequisites (APPROVE verdict exists, no conflicting merges)
2. Build merge plan from the proposal's Change Manifest
3. Present the plan to the user for approval
4. Pre-apply validation (confirm targets still match proposal assumptions)
5. Create docs/system/.pipeline-authorized marker (authorizes edits to system docs)
6. Apply each change from the Change Manifest to the target system docs
7. Remove the marker
8. Update tracking (PROPOSAL_TRACKER.md)
9. Auto-trigger verify mode

Usage: /cl-reviewer merge [P-NNN-slug.md]

Fix Mode

When helping the user address blocking issues from a review, read references/fix-mode.md and follow its process.

Fix mode reads the latest review for a proposal, lists all blocking issues, and suggests specific edits to the proposal to resolve each one. Edits are applied to the proposal file (not system docs — no hook bypass needed). After all fixes are applied, a re-review is auto-triggered.

The workflow:

1. Read the latest review for the proposal
2. List all blocking issues with context
3. For each issue, suggest specific edits to the proposal
4. Apply edits to the proposal file (with user confirmation)
5. Auto-trigger re-review

Usage: /cl-reviewer fix [P-NNN-slug.md]

Correction Mode

When applying targeted fixes from audit findings, verify issues, or spec review results, read references/correction-mode.md and follow its process.

Correction mode is the lightweight alternative to the full research -> proposal pipeline. It's for issues where the diagnosis is already clear (from an audit, verify, or spec review) and the fix is obvious. The audit report IS the research — no additional investigation needed.

The workflow:

1. Read the source finding (audit report, verify report, spec review, or user observation)
2. Build a corrections manifest — a table of what changes, with source attribution
3. Present the manifest to the user for approval
4. Create docs/system/.pipeline-authorized marker (operation: correct)
5. Apply the corrections surgically — no scope creep
6. Remove the marker
7. Spot-check the changes (lightweight, not a full verify)
8. Log to docs/reviews/proposals/CORRECTIONS_[DATE].md

Use corrections for: stale references, terminology drift, broken links, spec/doc mismatches, factual errors caught by audit, consistency alignment, orphaned TODOs.

Use the full pipeline for: new concepts, architectural changes, design decisions, restructuring, anything where the "right fix" isn't obvious.

Usage: /cl-reviewer correct [AUDIT_DATE.md|VERIFY_P-NNN.md]

Sync Mode

When checking code-doc alignment, read references/sync-mode.md and follow its process.

Sync mode detects drift between what system docs claim and what the codebase actually does. It extracts verifiable claims from system docs (file structure, dependencies, API shapes, configuration, etc.), checks them against the actual code, and produces an advisory report.

Sync mode does NOT modify any documentation — it produces a report that feeds into corrections (/cl-reviewer correct SYNC_DATE.md) or research cycles.

Two scope options:

• Full scan (/cl-reviewer sync): Verify all extractable claims against the codebase
• Git-diff (/cl-reviewer sync --since <ref>): Only check claims in areas where code changed since <ref>

Output: {docsRoot}/reviews/audit/SYNC_[YYYY-MM-DD].md — alongside audit reports.

Usage: /cl-reviewer sync or /cl-reviewer sync --since <ref>

DECISIONS.md Reconciliation: When running sync (either full or git-diff scoped), include a DECISIONS.md reconciliation pass:

1. Read all active decisions from DECISIONS.md
2. For each decision with a verifiable implementation claim (technology choice, pattern, configuration value, convention):
   • Extract the claim
   • Check it against the codebase (same claim extraction mechanism as doc-code sync)
3. Report contradictions: "D-NNN says [X] but code does [Y]"
4. Distinguish:
   • Intentional evolution: The decision may need updating (code was changed deliberately)
   • Accidental drift: The code may need fixing (decision was forgotten during implementation)
5. Include reconciliation results in the sync report under a "Decision Reconciliation" section

Design Review Mode

When reviewing design artifacts, read references/design-review-mode.md and follow its process.

Design review validates design artifacts (DESIGN_SYSTEM.md, UI_SCREENS.md, .pen files) across three dimensions: design vs. system docs (do designs match PRD requirements?), design vs. code (do naming and token conventions align with the codebase?), and internal consistency (are tokens used consistently, are naming patterns uniform?). Uses Pencil MCP tools when available for deeper verification.

Output: {docsRoot}/reviews/design/DESIGN_REVIEW_[YYYY-MM-DD].md

Usage: /cl-reviewer design-review

Guidelines

• Be substantive, not performative. A short review with one real finding beats a long one padding out minor preferences. If the proposal is solid, say so.

• Respect the iteration that's already happened. Don't re-litigate decisions that were clearly deliberate. Focus on things the author and AI might have missed — especially cross-system consistency, which is hard to catch in an iterative loop focused on one doc.

• Be specific. Bad: "This section is unclear." Good: "Section 3.2 says events are processed synchronously, but the architecture doc's event bus section describes async processing — which should win?"

• Blocking vs. non-blocking matters. The author needs to know what must change vs. what could improve. Don't bury a critical conflict in a list of nice-to-haves.

• Your unique value is cross-referencing. A proposal might be internally perfect but introduce a contradiction with the architecture that nobody caught because they were focused on the proposal in isolation. That's why you read the manifest and system docs.

• Don't be afraid to approve. The goal isn't to find problems — it's to catch real ones before they propagate into system docs. A clean APPROVE is a valid outcome.

• Track everything. Update PROPOSAL_TRACKER.md after reviews and verifications. Update DECISIONS.md whenever a conflict is resolved, a proposal is rejected, a verification finding overrides proposal intent, or an audit leads to a fix-vs-research decision. The pipeline relies on accurate state.

• Decision flow: check before flagging. When reviewing a proposal, check DECISIONS.md for prior decisions in the same area. If a proposal seems to contradict a prior decision, distinguish between: (a) intentional reversal (the proposal explicitly addresses the old decision) and (b) accidental contradiction (the proposal author may not have known about the prior decision). Flag (b) as a blocking issue; note (a) as context. When merging, update DECISIONS.md if the merge supersedes a prior decision.

Parking Protocol

When a finding surfaces during any mode that is NOT the current focus:

1. Check first: Read PARKING.md active section. If a similar item exists, add context to it rather than creating a duplicate.

2. Classify: architectural (blocks progress) | incremental (can wait) | scope-expansion (new feature idea). Default to incremental if uncertain.

3. Record in PARKING.md -> Active section:

   • Assign next EC-NNN ID
   • Fill all columns (Concept, Classification, Origin, Date, Impact, Notes)

4. Tell the user: "Found [classification] issue: [brief]. Parked as EC-NNN." If architectural: "This may affect implementation -- I'll flag it at spec/start."

5. Continue current work. Don't derail.