Arc Refining

Refiner

Overview

Transform design documents into structured XML specifications. The spec becomes Source of Truth - downstream skills cannot invent requirements.

When NOT to Use

• No design doc exists yet (brainstorm first)
• Task is small enough that a structured spec is overhead

Core Rules

1. ask, don't assume - if unclear, ask user; never invent requirements
2. source of truth - spec.xml is authoritative; downstream quotes it
3. checklist validation - complete checklist before proceeding
4. iterative refinement - ask 2-3 clarifying questions per iteration

Input Requirements (Block If Missing)

Before drafting spec.xml, verify the design doc includes:

• REFINER_INPUT section
• At least one functional requirement

If missing, STOP and ask for the missing content.

quality checklist

Before moving to the next stage, confirm:

• every requirement has acceptance criteria
• no vague terms ("should", "maybe", "usually")
• dependencies identified
• user confirms: "Is this spec complete?"

workflow guidance

Ask at least 2-3 clarifying questions. The agent decides when it is enough. The user can say "enough, continue" at any time.

Workflow

digraph refiner {
    "Analyze design.md" -> "Draft spec.xml";
    "Draft spec.xml" -> "Checklist complete?";
    "Checklist complete?" -> "Ask 2-3 clarifying questions";
    "Ask 2-3 clarifying questions" -> "User says continue?";
    "User says continue?" -> "Update spec" [label="refine"];
    "Update spec" -> "Checklist complete?";
    "User says continue?" -> "Self-validate" [label="yes"];
    "Self-validate" -> "Output specs/";
}

output structure

creates specs/details/ directory with:

specs/
├── spec.xml              # main spec (overview, cross_cutting, details index)
└── details/
    ├── authentication.xml
    ├── api-endpoints.xml
    └── data-models.xml

Commit Requirements

After generating or updating specs:

git add specs/spec.xml specs/details/
git commit -m "docs: refine spec for <topic>"

self-validation

before finalizing, verify:

• all required fields exist (id, title, description, acceptance_criteria)
• all ids unique
• all references valid
• every criterion has <trace> to source
• every input requirement has ≥1 criterion

asking user (example)

checklist review:

gaps found:
- fr-auth-003 lacks error handling criteria
- "password strength" undefined

questions:
1. what should happen when password reset fails?
2. what are the specific password strength requirements?
3. are there any other authentication edge cases to handle?

red flags - stop

• "user seems happy, let's proceed"
• "i can make reasonable assumptions"
• "we can refine later in implementation"
• "skipping clarifying questions"

all mean: keep asking until checklist complete and user confirms.

completion format

✅ refiner complete

• iterations: 6
• checklist: complete ✓
• output: specs/spec.xml + 3 detail files (committed)
• ready for: arc-planning

blocked format

⚠️ refiner blocked

• issue: user unavailable for clarification
• checklist incomplete: missing 3 acceptance criteria definitions
• action: resume when user returns

Converted and distributed by TomeVault — claim your Tome and manage your conversions.