Dialectical Refinement

Overview

Surface hidden complexity before implementation through adversarial tension. A single reviewer tends toward over-engineering or over-simplification; opposing passes converge on correct scope.

When to Use (Proactive Triggers)

/breakdown <spec.md>

/refine

/breakdown

/refine <task-id>

Protected Categories

Before any simplification, identify items that must NOT be cut:

--json

--range

--auto

Tag protected items early. The Proposer phase should not propose cutting them.

The 5-Phase Process

Phase 1: Formalize (Analyst)

Goal: Surface ambiguity and tag protected items.

• What terms are undefined?
• What's the input/output contract?
• What exists vs. genuinely new?
• What are acceptance criteria?
• What dependencies are implicit?
• Which items fall into protected categories?

Output: Detailed spec with gaps called out and protected items tagged.

Checkpoint: If significant unknowns remain (scope, architecture, must-have vs nice-to-have), ask 1-3 focused questions before proceeding.

HITL Clarification Protocol: When asking users, use

AskUserQuestion

Phase 2: Propose Cuts (Proposer)

Goal: Identify candidates for simplification—propose, don't execute.

The Proposer suggests cuts with confidence levels. It does NOT produce a reduced spec; it produces a list of proposals for the Advocate to argue against.

Output Format:

## PROTECTED (never cut)
- [List items from protected categories with rationale]

## PROPOSED CUTS

### Strong Cut Candidates (high confidence)
- `<item>` — [Rationale: clearly deferrable or unnecessary]

### Moderate Cut Candidates (medium confidence)
- `<item>` — [Rationale: could defer, but note trade-offs]

### Weak Cut Candidates (low confidence, protect carefully)
- `<item>` — [Rationale: seems optional, but may have hidden value]

Key Constraint: Proposer argues for cuts but does NOT execute them. The Advocate reviews each proposal.

Phase 3: Challenge (Advocate)

Goal: Argue against proposed cuts, restore what matters.

The Advocate receives the Proposer's proposals and responds to EACH one:

Output Format:

## ADVOCATE RESPONSES

### Strong Cuts — Agreed
- `<item>` — Agree: [brief reason]

### Strong Cuts — Contested
- `<item>` — Contest: [why this should stay]

### Moderate Cuts — Agreed
- `<item>` — Agree, defer to phase 2

### Moderate Cuts — Contested
- `<item>` — Contest: [hidden value / future cost of adding later]

### Weak Cuts — Recommendations
- `<item>` — [Keep/Cut with reasoning]

### Cheap Additions Missed
- [Items not in spec that are low-effort, high-impact]

Key Constraint: Advocate argues from the proposals, not from memory. Every proposal gets a response.

Phase 4: Scope Lock (Checkpoint)

Goal: Verify essential scope before synthesis.

Before the Judge produces final output, verify:

--json

"Too Thin" Indicators:

• Fewer than 5 commands/features for a system? ⚠️
• Removed structured output (

  --json

  )? ⚠️
• Removed range/anchor/batch capabilities? ⚠️
• All m+ tasks cut to xs/s? ⚠️

If 2+ indicators trigger, return to Phase 3 with guidance to restore scope.

Phase 5: Synthesize (Judge)

Goal: Produce actionable, externally-reviewable spec with quality gates.

• Resolve remaining Proposer/Advocate debates
• Write concrete implementation details
• Define testable acceptance criteria
• Document OUT OF SCOPE explicitly
• Ensure spec is standalone-reviewable (see below)

Standalone Context Requirement:

The final spec must be reviewable by an external agent without access to conversation history. Include:

1. Introduction — What this spec is and why it exists (2-3 sentences)
2. Context appendix (if spec is part of larger system):
   • Brief description of the parent project/system
   • Where this spec fits in the bigger picture
   • Key constraints inherited from the larger context
   • Reference this appendix in the introduction

Keep context token-efficient: enough for an external reviewer to assess readiness, not a full project overview.

Spec Structure:

## Introduction
[What + Why in 2-3 sentences. If partial: "See Appendix A for project context."]

## Scope
[What's being built]

## Acceptance Criteria
[Testable outcomes]

## Out of Scope
[Explicit boundaries]

## Appendix A: Project Context (if needed)
[Token-efficient big picture: ~100-200 words max]

Synthesis Quality Check:

--json

If 2+ indicators fail, output REVISE with specific gaps—don't ship a thin spec.

Quality Gate:

• GO — Ready to implement
• GO with caveats — Workable with listed risks
• REVISE — Too thin or too vague, needs another pass with specific guidance

Early Exit Rules

Not every spec needs all 5 phases:

If the Proposer has no cuts and Advocate has no additions, skip Scope Lock and proceed to Synthesize.

Complexity Estimation

Rule of thumb: If you can't describe implementation in 2-3 sentences, it's l or higher.

Command Reference

/refine <target>

Runs 5-phase refinement on a bead or spec file.

1. Reads target
2. Runs 5 sequential phases (separate agents for adversarial tension)
3. Presents synthesized spec
4. Updates bead, adds

   refined

   label

/breakdown <target>

Decomposes epic/spec into tasks.

1. Refines target first (if not already)
2. Proposes task breakdown with complexity estimates
3. Creates beads with dependencies and labels
4. Links tasks to parent epic

Breakdown Output Rules

refined

needs-refinement

Tasks get:

• parent-child

  dep to source epic

• blocks

  for sequential dependencies
• Complexity estimate
• Brief description (details filled at refinement)

Integration with bd

# Find work needing refinement
bd list --labels needs-refinement

# Find refined work ready to implement
bd ready --labels refined

# Find epics needing breakdown
bd list --type epic --labels needs-breakdown

Refined Spec Criteria

A spec is refined when:

1. Standalone — Introduction + context sufficient for external review
2. Concrete — Files, functions, line estimates clear
3. Bounded — OUT OF SCOPE section exists
4. Testable — Acceptance criteria are observable
5. Sized — Complexity reflects actual uncertainty
6. Unblocked — Dependencies identified/tracked

Anti-Patterns

• Refinement theater — Running phases without meaningful changes
• Premature refinement — Refining backlog items that may never be done
• Skipping Advocate — Proposer cuts can go too far without challenge
• Executing cuts in Proposer — Proposer proposes; Advocate + Judge decide
• One-person dialectic — Use separate agents per phase for genuine tension
• Ignoring Scope Lock — Too Thin indicators exist for a reason

Why Separate Agents Per Phase

Each phase agent receives only previous output + goals, not internal reasoning. This prevents self-reinforcing mistakes. The Proposer shouldn't remember why the Analyst included something—it should propose cuts from scratch. The Advocate shouldn't remember the Proposer's reasoning—it should challenge each proposal independently.

Resources

For examples and extended reference material, see:

• references/examples.md

  — Before/after refinement examples