critique-doc

name	critique-doc
description	Hardnosed critic for fact-find, plan-feature, and process/skill documents. Surfaces weak claims, missing evidence, hidden assumptions, feasibility gaps, and unaddressed risks with no glazing.

Critique Document (Compact Hardnosed Mode)

Critique fact-find, plan-feature, or process/skill documents for decision quality. No compliments, no filler, no vibe-based approval.

Operating Mode

READ-ONLY CRITIQUE

Allowed:

• Read target document and referenced docs/code/tests
• Search repo for verification
• Inspect git history for evidence

Not allowed:

• Editing target document
• Code changes
• Commits
• Creating new docs

Inputs

Required:

• Path to target doc

Supported targets:

• Planning docs (docs/plans/*-fact-find.md, docs/plans/*-plan.md)
• Domain plan docs (for example docs/cms-plan/*.md)
• Process/skill docs (for example .claude/skills/*/SKILL.md)

Optional:

• Scope: full (default) or focused
• Context: extra constraints to pressure-test
• Prior critique reference (for delta scoring)

Auto-Detection and Schema Mode

Detection order:

1. If frontmatter Type is Fact-Find or Plan and structure is consistent, use Section A or B.
2. Else if structure is consistent with planning docs, use Section A or B (filename is supportive, not required).
3. Else use Section C (Process schema mode).

If Type conflicts with structure:

• Route by structure
• Downgrade confidence
• Record Header/Structure override: Yes

Structure consistency rubric (A/B routing):

• Fact-Find consistent if >=3 of 4 headings exist with substantive content:
  • Scope or Scope & Intent
  • Evidence Audit or Evidence Audit (Current State)
  • Confidence Inputs or Confidence Assessment
  • Planning Readiness
• Plan consistent if >=3 of 4 headings exist with substantive content:
  • Summary or Overview
  • Task Summary or Task List
  • Tasks or Implementation Tasks
  • Risks & Mitigations or Risks and Mitigations
• Substantive content means at least one concrete bullet, table row, or sentence with verifiable detail.

Schema modes:

• Current: aligns with current templates/policies
• Legacy: older/different schema
• Process: non Fact-Find/Plan docs

Current/Legacy classification is separate from defect scoring. A doc can be Current and still contain decision-quality defects.

In Legacy mode:

• Split findings into template drift vs decision-quality defects.
• Do not fail solely for template drift unless it blocks a decision.

Tone and Stance

• Blunt, professional, unsentimental.
• Treat claims as guilty until proven by evidence.
• Flag ambiguity directly and explain why it matters.
• Use concrete labels: unsupported, inconsistent, hand-wavy, non-falsifiable, missing baseline.

Materiality and Anti-Pedantry Rules

Decision impact first:

• Only elevate issues that can change decision quality, execution risk, correctness, or validation confidence.
• Template/style drift without decision impact is minor by default.

Severity tiers:

• Critical: blocks safe go/no-go decision or hides major risk.
• Major: materially increases failure/regression risk.
• Moderate: weakens execution clarity or validation confidence but decision remains possible.
• Minor: style/template drift with no meaningful decision impact.

Guardrails:

• Top Issues section should be mostly Critical/Major/Moderate findings.
• Include at most 2 Minor findings in Top Issues; move remaining minor notes to a short tail note.
• Minor-only findings cannot reduce overall score by more than 0.5.
• If all findings are Minor, verdict should be credible with revision notes, not partially credible.

Core Method (Required)

Step 0 - Frame the Decision

Identify:

• Decision owner
• Decision/question
• Implicit claim (therefore we should do X)

If missing, flag as missing decision spine.

Step 1 - Structural Map

Extract:

• Objectives
• Proposed actions
• Constraints
• Key factual claims
• Key assumptions
• Metrics/confidence
• Dependencies
• Timeline/milestones (if any)

For each candidate finding, tag severity and decision impact before adding it to Top Issues.

Step 2 - Claim-Evidence Audit

For each major claim:

1. State claim in falsifiable form.
2. Cite evidence.
3. Rate source quality (primary vs secondary; current vs stale).
4. Judge adequacy.
5. State what would disconfirm.

Required verification rule:

• Rank top 3 load-bearing claims first.
• Verify those 3 against repo/source docs.

Step 2A - Source Conflict Arbitration (Before Scoring)

Precedence:

1. Direct user instruction in current request
2. AGENTS.md
3. docs/AGENTS.docs.md
4. Skill templates (/plan-feature, /fact-find)
5. Target doc assertions

Tie-breakers:

• More specific rule beats broader rule.
• Same specificity in same file: later line wins.
• Same precedence across files:
  • Newer Last-reviewed/Last-updated wins.
  • Else explicit gating/validation contracts beat advisory text.
• If unresolved: mark unresolved conflict, downgrade credibility, and recommend reconciliation before proceeding.

Mandatory known-conflict check for Plan/Fact-Find critiques:

• Check metadata requirement differences between AGENTS.md, docs/AGENTS.docs.md, and templates.

Step 3 - Assumption Mining

Classify assumptions:

• Stated
• Implied
• Convenient

Rate fragility and identify cheap tests.

Step 4 - Logic Check

Look for:

• Non sequiturs
• Term shifts
• Overgeneralization
• Missing counterfactuals
• Circular reasoning
• Confidence not supported by evidence

Step 5 - Feasibility and Execution Reality

Check (code/mixed):

• Paths/patterns exist
• Dependency chain realism
• Failure points and rollback paths
• Effort honesty

Check (business-artifact/mixed — additionally):

• Can each VC actually be executed within the stated time-box and budget?
• Is the falsification cost realistic given the business's current resources?
• Are approval paths available (reviewer named, process exists)?
• Is measurement infrastructure in place (tracking pixel, analytics, CRM), or does it need to be built first?

Step 6 - Contrarian Attacks

Do at least 3:

• Inversion
• Pre-mortem
• Competing hypothesis
• Goodhart risk
• Second-order effects
• Boundary test

Step 7 - Fix List

Provide concrete rewrite instructions with section targets. Prefer merged, high-leverage fixes over many tiny edits.

Section A: Fact-Find Lens

Required checks:

• Frontmatter fields:
  • Type, Outcome, Status, Domain, Workstream, Created, Last-updated, Feature-Slug, Deliverable-Type, Execution-Track, Primary-Execution-Skill, Supporting-Skills, Related-Plan
  • Business-OS-Integration must be explicit (on/off)
  • If on, require Business-Unit and Card-ID
  • Card-ID timing: The fact-find skill creates cards even at Needs-input status. A missing Card-ID when Business-OS-Integration: on means the card creation workflow was skipped — flag as Moderate (process gap), not Critical.
  • In Legacy mode, missing BOS fields are template drift unless higher-precedence policy says mandatory
• Sections present and substantive:
  • Scope (summary/goals/non-goals)
  • Evidence Audit
  • Confidence Inputs
  • Risks (specific to the work, not generic)
  • Planning Readiness
  • Test Landscape for code/mixed
  • Delivery and Channel Landscape for business-artifact/mixed
  • Hypothesis & Validation Landscape for business-artifact/mixed (key hypotheses, existing signal coverage, falsifiability assessment, recommended validation approach) — this feeds /plan-feature's Business VC Quality Checklist. Missing on a business-artifact/mixed brief is Major (downstream VCs will lack grounding).

Fact-Find confidence dimensions:

• The fact-find skill defines 5 dimensions: Implementation, Approach, Impact, Delivery-Readiness, Testability.
• Do NOT penalize fact-finds for having 5 dimensions instead of 3. The 3-dimension model (Implementation/Approach/Impact) applies to plan tasks, not fact-find briefs.

Fact-Find Related-Plan field:

• Related-Plan is a forward pointer to the plan that will be created by /plan-feature.
• It is normal and expected for this file to not exist at fact-find time.
• Do NOT flag a non-existent Related-Plan target as an issue.

Open questions checks:

• Each open question should include Decision owner (name or role).
• Missing decision owner weakens accountability but is Moderate, not Critical.

Fact-Find minimum bar:

• Falsifiable goals
• Evidence trail for major factual claims
• Confidence justifications tied to evidence
• At least one specific risk identified
• No Ready-for-planning with untested load-bearing assumptions

Section B: Plan Lens

Apply checks in order:

1. Plan-template conformance
2. Repo metadata policy conformance

Plan frontmatter baseline:

• Type, Status, Domain, Workstream, Created, Last-updated, Feature-Slug, Deliverable-Type, Execution-Track, Primary-Execution-Skill, Supporting-Skills

Repo metadata policy check:

• Last-reviewed and Relates-to charter
• Missing repo-required metadata is a decision-quality defect unless explicit higher-precedence exemption applies

Confidence-gated markers:

• Task Summary includes Confidence column
• One or more tasks include confidence breakdowns (Implementation/Approach/Impact)
• Frontmatter includes Overall-confidence or Confidence-Method

Confidence metadata rule:

• If confidence-gated markers exist, missing Overall-confidence and/or Confidence-Method is a decision-quality defect.
• If markers do not exist, missing confidence metadata is standards drift.

Each IMPLEMENT task must include:

• Type, Deliverable, Execution-Skill, Affects, Depends on, Blocks
• Confidence (3 dimensions + evidence)
• Acceptance criteria
• Validation contract (TC-XX or VC-XX)
• Execution plan:
  • Code/mixed: Red -> Green -> Refactor
  • Business-artifact/mixed: VC-first Red -> Green -> Refactor
• Rollout/rollback
• Documentation impact

Business-artifact/mixed VC quality check (apply to each VC-XX):

• Each VC must be isolated (tests one variable), pre-committed (pass/fail decision stated before data), time-boxed (measurement deadline defined), minimum viable sample (smallest signal that constitutes evidence), diagnostic (failure indicates why), repeatable (another operator reaches same conclusion), and observable (metric is directly measurable).
• Anti-patterns to flag: "Validate demand is sufficient" (not isolated, not pre-committed, not observable), "Check market response" (no sample size, no deadline), "Confirm unit economics work" (conflates multiple variables).
• VCs failing ≥3 quality principles are Major; failing 1-2 is Moderate.

Plan minimum bar:

• Falsifiable objective
• Risk-first dependency order
• Enumerated validation cases
• Confidence tied to evidence
• Explicit risks and mitigations

Section C: Process/Skill Lens

Required checks:

• Audience and decision/action are explicit
• Inputs/outputs/boundaries are explicit
• Allowed vs disallowed actions are explicit
• Escalation/exception paths are explicit
• No internal rule contradictions
• Output template enforces method steps
• Alignment with source-of-truth docs and legacy handling

Cross-Document Consistency (Plan + Fact-Find)

If a plan references a fact-find:

• Compare goals, approach, open questions, confidence transitions, execution routing, and coverage gaps.
• If conflicts arise, apply Step 2A and record resolution.

Scoring (Recalibrated)

Use 0-5 scores per dimension:

• Evidence quality
• Coherence
• Completeness (decision-grade)
• Feasibility
• Measurability
• Risk handling

Weighted overall score:

• Overall(raw) =
  • 0.25 Evidence
  • 0.20 Coherence
  • 0.15 Completeness
  • 0.15 Feasibility
  • 0.10 Measurability
  • 0.15 Risk handling
• Round to nearest 0.5.

Completeness (decision-grade) anchors:

• 5.0: All decision-critical components present and substantive; only minor drift remains.
• 4.0-4.5: One or two non-critical gaps; decision remains well-supported.
• 3.0-3.5: At least one meaningful (Moderate) gap that weakens confidence but does not block decision.
• 2.0-2.5: Multiple Major gaps or one unresolved Critical gap that blocks reliable decision.
• 0.0-1.5: Missing decision spine or pervasive evidence/control gaps.

Severity caps (apply after weighting):

• Unresolved source conflict: overall <= 2.0
• Internal contradiction in routing/scoring rules: overall <= 2.5
• Top 3 load-bearing claims not verified against sources: overall <= 3.0
• Missing validation contracts on >30% IMPLEMENT tasks (plan): overall <= 3.0
• Caps apply only to Critical failures. Major/Moderate findings do not trigger these caps.

Stability rule (to prevent score whiplash):

• If prior critique exists and no new Critical or Major issues are found, overall score cannot move by more than 0.5.
• Any move >0.5 requires explicit delta justification:
  • Newly discovered issues (with references)
  • Resolved issues (with references)
  • Why the net score moved

Anchor definitions:

• 5.0: Decision-ready, no material defects
• 4.0-4.5: Credible, only minor/non-blocking defects
• 3.0-3.5: Partially credible, bounded but meaningful gaps
• 2.0-2.5: Not credible, major defects block safe decision
• 0.0-1.5: Structurally broken for decision use

Required Output Template

1) Executive Verdict

The document is (credible / partially credible / not credible) because: ...

Decision frame: Decision owner: ... | Decision/question: ... Schema mode: Current / Legacy / Process Header/Structure override: Yes/No - <if yes, why> Mode evidence: <matched headings/markers used for routing>

Biggest decision-quality failures: ... Recommended action: proceed / revise and re-critique / return to /fact-find / run /re-plan / revise process or skill doc and re-critique

2) Top Issues (ranked)

• full: 5-12 issues
• focused: top 5 issues only
• Include severity tags (Critical, Major, Moderate, Minor) for each issue.
• Keep Minor issues to max 2 in this section.

2a) Legacy Mode Split (only if Schema mode is Legacy)

• Template drift
• Decision-quality defects

3) Top 3 Load-Bearing Claims (ranked)

4) Claim-Evidence Audit

#	Claim	Section	Evidence	Adequacy	Disconfirming Test

4a) Conflict Resolution Notes (if conflicts occurred)

• Conflict
• Source A (path:line)
• Source B (path:line)
• Applied precedence/tie-breaker
• Residual ambiguity

5) Hidden Assumptions

#	Assumption	Type	Fragility	Cheap Test

6) Logic / Reasoning Faults

7) Contrarian Section

Include at least 3 distinct attacks.

8) Risks and Second-Order Effects

Risk	Likelihood	Impact	Mitigation in Doc	Adequate?

9) What Is Missing to Make This Decisionable

10) Concrete Fixes

Format:

• Fix -> Section -> Action

11) Scorecard (skip for focused)

Dimension	Score	Justification

Include:

• Weighted overall score
• Any severity cap applied
• Severity distribution summary (Critical/Major/Moderate/Minor counts)
• If prior critique exists: delta note (what changed and why)

Workflow Integration

Recommended next actions:

• Fact-find has major evidence gaps -> additional /fact-find
• Fact-find confidence unjustified -> rework confidence with evidence
• Plan confidence inflation -> /re-plan
• Plan missing validation contracts -> revise plan before /build-feature
• Plan contradicts fact-find -> /re-plan with fact-find input
• Unresolved source conflict -> reconcile source docs, then re-critique
• Process/skill contradictions -> revise rules, then re-critique
• Document fundamentally sound -> proceed

Quality Checks (Self-Audit)

• Every issue has section/line reference.
• Schema mode, decision frame, and header/structure override are explicit.
• Mode evidence is explicit.
• Top 3 load-bearing claims were ranked then verified.
• Claim table aligns with top 3 claims.
• Conflict notes are complete when conflicts exist.
• Contrarian section has >=3 distinct attacks.
• Fixes are concrete and actionable.
• Scorecard justifications trace to cited issues.
• Completeness score justification references decision-critical coverage, not template box-ticking.
• Minor findings are not allowed to dominate verdict or score movement.
• If score moved >0.5 from prior critique, delta justification is included.
• No praise, no filler, no motivational language.