# Self-Critique Protocol — Business Spec

After compiling the initial spec (Phase 10, step 8), refine it through automated adversarial review before presenting to the user. The user sees only the final refined spec plus a deliberation log.

## Design Principle

**Gather all user input FIRST, then refine internally.** The user interacts only twice: (1) answering clarifying questions during Phases 1–9, and (2) approving or rejecting the final refined spec. The critique loop is a proxy for user review — it catches what the user would catch, so they don't have to do multiple revision rounds.

## When This Runs

- **After** the spec is written to file (Phase 10, step 8)
- **Before** presenting to the user (Phase 10, step 9)
- Fully automated — **NO questions to the user** during this phase
- The interactive Q&A phases (1–9) are complete; all user input has been gathered

## Protocol

Run up to **3 rounds** of critique-and-fix. Each round is a structured dialogue between the **Author** (the orchestrating skill) and the **Critic** (a spawned agent).

### Round 1: Initial Critique

1. **Critic pass** — Spawn a separate critic agent with the Round 1 Critic Prompt (below). The critic should run with the highest-capability model/mode available in the current runtime (see Runtime Adaptation table below). The critic reads the spec file and all available platform knowledge, then returns a structured findings table.

   **Runtime adaptation:**
   | Runtime | Critic mechanism |
   |---------|-----------------|
   | Claude Code | Agent tool, `subagent_type: general-purpose` (use strongest available model) |

2. **Author evaluates** — For each finding from the critic:

   | Verdict | Criteria | Action |
   |---------|----------|--------|
   | **ACCEPTED** | Valid + evidence + CRITICAL or HIGH severity | Apply fix to spec file |
   | **REJECTED** | No evidence, factually incorrect, or style-only | Log with detailed rejection reason |
   | **DEFERRED** | Valid but MEDIUM/LOW severity + non-blocking | Log for user awareness |

3. **Convergence check** — If 0 new CRITICAL or HIGH findings → **exit loop early**

4. **Update deliberation log** — Append round summary to the spec's `## Deliberation Log` section

### Round 2: Dialogue — Critic Responds

The critic receives Round 1 results and can:
- Raise **entirely new findings** not previously raised
- **Counter-argue** a rejected finding — ONLY with new evidence that directly addresses the rejection reason

1. **Critic pass** — Spawn a critic agent (same mechanism as Round 1) with the Round 2+ Critic Prompt (below). Include the Round 1 deliberation log so the critic sees what was accepted, rejected, and deferred.

2. **Author evaluates** — Same verdict table. Counter-arguments that provide genuinely new evidence are evaluated on merit. Counter-arguments that merely restate the original finding → **CIRCULAR** (auto-reject).

3. **Convergence check** — If 0 new CRITICAL/HIGH findings AND 0 accepted counter-arguments → **exit loop early**

4. **Update deliberation log** — Append round summary, distinguishing new findings from counter-arguments.

### Round 3: Final Pass (if needed)

Same as Round 2. Any finding rejected twice (original + counter-argument) **cannot be raised again**. This is the hard termination point — the loop ALWAYS exits after Round 3.

### Fallback (No Agent Capability)

If the runtime does not support spawning separate agents (some IDE targets), perform **inline self-critique**:

1. After writing the spec, pause and switch to "critic mode" mentally
2. Systematically check each rubric item (CR-1 through CR-6) against the spec
3. For each finding, apply the same ACCEPT/REJECT/DEFER verdict
4. Write the deliberation log with the same format
5. Run all 3 rounds inline — less adversarial than a separate agent but still catches factual errors

The key difference: inline mode lacks the separation between author and critic, so the author may be biased toward defending their own work. Mitigate by strictly following the rubric and requiring evidence for every finding.

## Critic Rubric (Spec-Specific)

| # | Category | What to Check |
|---|----------|---------------|
| CR-1 | **Platform accuracy** | Does the spec reference entity types, GraphQL fields, template features, or capabilities that don't exist in Fluent? Verify against known entity types: ORDER, FULFILMENT, FULFILMENT_CHOICE, ARTICLE, RETURN_ORDER, LOCATION, INVENTORY_POSITION, WAVE, CONSIGNMENT, PRODUCT, CUSTOMER, CARRIER, VIRTUAL_CATALOGUE, NETWORK, CREDIT_MEMO, BILLING_ACCOUNT. Check GraphQL field and connection assumptions. Check Mystique template helper assumptions. |
| CR-2 | **Scope completeness** | Are all artifacts needed for the feature identified in §3 Scope? Missing workflow changes, settings, rules, manifest modifications, SDK components? Cross-check use cases (§5) against scope — every use case should map to at least one in-scope artifact. |
| CR-3 | **Assumption validity** | Is each assumption in §11 provably true or correctly flagged as unverified? Are there unstated assumptions hidden in use cases or business rules that should be explicit? |
| CR-4 | **Use case coverage** | Missing edge cases, failure modes, or zero-data scenarios? What happens when connections return empty, when counts are zero, when data is missing or malformed? |
| CR-5 | **Internal consistency** | Do sections contradict each other? Does §3 (scope) align with §9a (UI)? Does §6 (entities) match §5 (use cases)? Do acceptance criteria (§13) cover all use cases (§5)? Are risk mitigations (§10) feasible given the scope? |
| CR-6 | **Feasibility** | Can this be built as described using Fluent platform features? Are there platform limitations the spec ignores? Are query patterns, template helpers, or workflow features assumed without verification? |
| CR-7 | **Diagram quality** | Is §5a present when it should be (2+ actors OR 2+ use cases)? Does the actor map match §4 exactly (no missing/extra actors)? Does the user journey flow cover ALL use cases from §5 — can every UC-XX be traced in at least one diagram path? Do decision diamonds match business rules from §7 (reference BR-XX IDs)? Is the abstraction level correct — business language ("Order placed", "Pick items") NOT technical ("CREATED status", "SendEvent rule")? Is Mermaid syntax valid (flowchart has direction, no spaces in IDs, correct arrow types)? Are conditional diagrams (actor interaction, decision flow) included when their thresholds are met (3+ actors, 3+ branching conditions)? SKIP this check if the feature is single-actor, single-UC, no branching (extremely rare). |

## Round 1 Critic Prompt

```
You are a senior Fluent Commerce solution architect conducting an adversarial review of a Business Spec. Your job is to find ERRORS and GAPS — not style preferences. Think deeply and critically about every claim in the spec.

Read the spec at: {spec_path}
{If exists: Also read platform knowledge at: knowledge/platform/domain-model.md}
{If exists: Also read: accounts/<PROFILE>/knowledge/client/business-rules.md, accounts/<PROFILE>/knowledge/client/data-model.md}

{feedback_pitfalls}

Review against these 7 criteria:
1. Platform accuracy — entity types, GraphQL fields, Mystique template features
2. Scope completeness — missing artifacts needed for the feature
3. Assumption validity — unverified or incorrect assumptions
4. Use case coverage — missing failure/edge cases
5. Internal consistency — contradictions between sections
6. Feasibility — can it actually be built as described?
7. User journey diagrams — §5a has Mermaid diagram(s) showing actors, trigger, happy path, and decision points (skip if no human actors)

Rules:
- Every finding MUST include EVIDENCE: a specific platform constraint, GraphQL schema fact, documentation reference, or logical proof
- "I think" or "it seems" is NOT evidence — cite specifics or don't raise it
- Do NOT raise style, formatting, or wording issues
- Do NOT suggest adding features or requirements beyond the stated scope
- If a section correctly states "not applicable" or "out of scope", respect that
- Focus on things that would cause implementation failure, not aesthetic preferences
- Think about what a real implementation team would struggle with

Output format — one markdown table, nothing else:

| # | Severity | Category | Finding | Evidence | Proposed Fix |
|---|----------|----------|---------|----------|--------------|
| C1 | CRITICAL/HIGH/MEDIUM/LOW | CR-N | What's wrong | Proof it's wrong | How to fix it |

Severity guide:
- CRITICAL: Would cause implementation failure or produce incorrect behavior
- HIGH: Likely to cause issues during planning or implementation
- MEDIUM: Should fix but won't block implementation
- LOW: Minor improvement, non-blocking

If no issues found, output exactly: "No findings — spec passes all 7 criteria."
```

## Round 2+ Critic Prompt (Dialogue Mode)

For rounds 2 and 3, the critic receives the full deliberation context:

```
You are a senior Fluent Commerce solution architect conducting round {N} of an adversarial review.

Read the spec at: {spec_path}
{If exists: Also read platform knowledge at: knowledge/platform/domain-model.md}
{If exists: Also read: accounts/<PROFILE>/knowledge/client/business-rules.md, accounts/<PROFILE>/knowledge/client/data-model.md}

{feedback_pitfalls}

## Prior Round Context

The following findings were raised and evaluated in prior rounds:

### Accepted (already fixed in spec):
{For each accepted finding:}
- {finding_id}: {finding text} → Fix applied: {what changed}

### Rejected (author disagreed):
{For each rejected finding:}
- {finding_id}: {finding text}
  Evidence cited: {original evidence}
  Rejection reason: {why it was rejected}

### Deferred (noted for user):
{For each deferred finding:}
- {finding_id}: {finding text}

## Your Task

You may:
1. Raise **entirely new findings** not previously raised — apply the same 7 criteria
2. **Counter-argue** a rejected finding — BUT ONLY if you have NEW EVIDENCE that directly addresses the rejection reason. Simply restating the original finding or rephrasing it is NOT a counter-argument.

Counter-arguments must include:
- Reference: "Counter to {finding_id}"
- New evidence that wasn't in the original finding
- Why the rejection reason was incorrect or incomplete

Rules (same as Round 1, plus):
- Do NOT re-raise a finding with the same evidence — that's circular
- Do NOT argue about DEFERRED items — they're already noted for the user
- Counter-arguments without genuinely new evidence will be auto-rejected
- If a finding was rejected twice (original + counter), it CANNOT be raised again

Output format — same table. Mark counter-arguments clearly:

| # | Severity | Category | Finding | Evidence | Proposed Fix |
|---|----------|----------|---------|----------|--------------|
| C{N} | SEVERITY | CR-N | [NEW] or [COUNTER to C{X}]: finding text | evidence | fix |

If no new findings and no valid counter-arguments:
"No new findings — prior review was comprehensive."
```

## Guardrails

| Guardrail | Rule |
|-----------|------|
| **Max rounds** | 3 — hard cap, no exceptions |
| **Early exit** | 0 new CRITICAL/HIGH findings AND 0 accepted counter-arguments in a round → stop |
| **Critic capability** | Use the highest-capability model/mode available in the runtime. Claude Code: strongest available model via Agent tool. Other runtimes: strongest available model or inline deep-think. |
| **Counter-argument rule** | A rejected finding may be counter-argued ONCE with new evidence. If the counter-argument is also rejected, the finding is permanently closed. No third attempt. |
| **Evidence required** | Findings without specific evidence (platform doc, schema fact, logical proof) are auto-rejected |
| **Severity filter** | Only CRITICAL and HIGH findings trigger spec changes. MEDIUM/LOW are logged but don't block convergence |
| **No style changes** | Wording preferences, formatting opinions, subjective suggestions → auto-reject |
| **No scope expansion** | Critic cannot suggest adding features beyond stated scope → auto-reject |
| **No user interaction** | The entire loop runs without prompting the user. All decisions made by the author/evaluator. |
| **Deterministic termination** | Always exits after at most 3 rounds. No "one more round" extensions. |
| **Escalation** | CRITICAL finding rejected twice → ESCALATED for user arbitration (see Escalation Mechanism) |
| **Complexity scaling** | HIGH complexity specs get up to 5 rounds and dual critics (see Complexity-Based Scaling) |
| **Feedback integration** | Pre-flight reads prior feedback JSONL to seed known pitfalls (see Pre-Critique Feedback Check) |

## Escalation Mechanism

When a CRITICAL finding is rejected by the author AND the critic counter-argues with new evidence AND the author rejects the counter-argument — the finding is promoted to **ESCALATED** status instead of permanently closed.

**ESCALATED findings:**
1. Are presented to the user alongside the refined spec
2. Include both sides: the critic's evidence AND the author's rejection reasons
3. The user makes the final call (accept the fix, reject, or defer)

This prevents the author from silently dismissing legitimate critical issues. Only CRITICAL findings can be escalated — HIGH/MEDIUM/LOW follow the normal rejection rules.

**Escalation format in deliberation log:**

| # | Severity | Category | Finding | Evidence | Verdict | Action |
|---|----------|----------|---------|----------|---------|--------|
| C{N} | CRITICAL | CR-{N} | [COUNTER to C{X}] ... | [new evidence] | ESCALATED | User arbitration required |

## Pre-Critique Feedback Check

Before spawning the first critic, check for prior feedback:

1. **Read** `accounts/<PROFILE>/feedback/fluent-use-case-discover.jsonl` (if it exists)
2. **Extract** the 3 most relevant learnings for this spec's domain (entity types, feature type)
3. **Inject** extracted pitfalls into the critic prompt as `{feedback_pitfalls}`

If the file does not exist or has no relevant entries, omit the `{feedback_pitfalls}` placeholder from prompts.

**Pitfall injection format** (appended to critic prompt Rules section):

```
Known pitfalls from prior specs (address these proactively):
{feedback_pitfalls}
```

This ensures the critic checks for historically recurring issues without the author needing to remember them.

## Revision Re-Critique

When a spec is updated after initial approval (spec revision triggered by plan feedback or implementation discovery):

1. **Scope** — Re-run critique on CHANGED SECTIONS ONLY, not the entire spec
2. **Context** — Critic receives the original deliberation log + a diff of what changed
3. **Rounds** — Max 2 rounds (not 3) — the unchanged portions already passed review
4. **New findings** — Only findings related to the changed sections are valid; findings about unchanged text are auto-rejected
5. **Log** — Append to existing deliberation log as "### Revision Re-Critique — Round N"

This avoids re-litigating settled decisions while ensuring new content meets the same quality bar.

## Complexity-Based Scaling

Spec complexity determines critique intensity:

| Complexity | Threshold | Max Rounds | Critic Mode |
|-----------|-----------|------------|-------------|
| **Standard** | Below all thresholds | 3 | Single critic |
| **HIGH** | 4+ entity types OR 6+ use cases OR 3+ integrations | 5 | Dual critics (see Multi-Critic Mode) |

**How to assess:** Count distinct entity types in §6, use cases in §5, and external integrations in §7. If ANY threshold is met → HIGH complexity.

HIGH complexity specs benefit from more rounds because:
- More entity types = more cross-entity interaction paths to validate
- More use cases = more edge cases and failure modes
- More integrations = more external dependency risks

## Multi-Critic Mode

HIGH complexity specs trigger dual parallel critics instead of a single critic:

### (a) Platform Critic
- **Focus:** CR-1 (Platform accuracy), CR-6 (Feasibility)
- **Expertise:** Entity types, GraphQL schema, Mystique templates, workflow patterns, platform constraints
- **Prompt addition:** "Focus exclusively on platform accuracy and feasibility. Ignore scope, assumptions, use cases, and consistency — another critic handles those."

### (b) Requirements Critic
- **Focus:** CR-2 (Scope completeness), CR-3 (Assumption validity), CR-4 (Use case coverage), CR-5 (Internal consistency)
- **Expertise:** Requirements engineering, edge cases, contradiction detection, completeness analysis
- **Prompt addition:** "Focus exclusively on scope, assumptions, use cases, and consistency. Ignore platform accuracy and feasibility — another critic handles those."

**Merge protocol:**
1. Run both critics in parallel (same round)
2. Merge findings into a single table, prefixed with `[PLAT]` or `[REQ]`
3. Author evaluates all findings using the standard verdict table
4. **Conflicting findings** (one critic says X is correct, the other says X is wrong) → both findings are ESCALATED for user arbitration
5. Convergence check applies to the merged finding set

Standard complexity specs use a single critic covering all 7 criteria.

## Deliberation Log Format

Append this section to the spec file, between the Traceability Matrix and the Recommendation:

```markdown
## Deliberation Log

### Round 1 — Initial Critique

| # | Severity | Category | Finding | Evidence | Verdict | Action |
|---|----------|----------|---------|----------|---------|--------|
| C1 | CRITICAL | CR-1 | [finding text] | [evidence] | ACCEPTED | Applied: [what changed in spec] |
| C2 | HIGH | CR-4 | [finding text] | [evidence] | REJECTED | Reason: [why it's wrong] |
| C3 | MEDIUM | CR-2 | [finding text] | [evidence] | DEFERRED | Noted for user awareness |

### Round 2 — Dialogue

| # | Severity | Category | Finding | Evidence | Verdict | Action |
|---|----------|----------|---------|----------|---------|--------|
| C4 | HIGH | CR-3 | [NEW] [finding text] | [evidence] | ACCEPTED | Applied: [what changed] |
| C5 | HIGH | CR-4 | [COUNTER to C2] [new argument] | [new evidence] | ACCEPTED | Overturned C2 rejection. Applied: [fix] |
| C6 | MEDIUM | CR-5 | [COUNTER to C2] [restated argument] | [same evidence] | CIRCULAR | Auto-rejected: no new evidence |

### Round 3 — Final Pass
...

### Summary
- **Rounds:** N (exit: [clean pass / converged / max reached])
- **Findings:** X total — Y accepted, Z rejected, W deferred, V counter-argued
- **Counter-arguments:** A raised, B accepted (overturned prior rejections), C rejected
- **Spec changes:** [list of all accepted changes applied, in order]
- **Open items for user:** [list of deferred findings the user should be aware of]

### User-Facing Summary

> **Internal review:** N rounds, X findings (Y fixed, Z deferred for your review).
> Key changes: [1-2 sentence summary of most impactful fixes].
> [If escalated items exist:] **Requires your decision:** [list escalated findings with both sides].
> [If deferred items exist:] **For your awareness:** [list deferred findings].
```

If Round 1 finds 0 issues:

```markdown
## Deliberation Log

### Round 1 — Initial Critique
No findings — spec passed all 7 criteria on first review.

### Summary
- **Rounds:** 1 (exit: clean pass)
- **Findings:** 0
```
