/synthex:refine-requirements/synthex:refine-requirements

#What it does, end-to-end

/synthex:refine-requirements/synthex:refine-requirements is the Discover-phase quality gate for the PRD. It improves an existing requirements document by running it through a multi-agent reviewer loop focused on clarity, completeness, and communicability — and writes the improvements directly back to the same file.

It deliberately does not produce an implementation plan. The output is one artifact: a cleaner PRD. Plan-writing lives in /synthex:write-implementation-plan/synthex:write-implementation-plan, which this command is the prerequisite to.

Each invocation:

1. Loads project config from .synthex/config.yaml (or plugin defaults) — primarily the reviewer roster and refine_requirements.review_loops overrides.
2. Reads the PRD at docs/reqs/main.md (configurable via documents.requirements).
3. Gathers technical context from docs/specs/, CLAUDE.md, package.json, and the surrounding codebase. This is what lets the command answer reviewer questions from existing knowledge rather than escalating them to you.
4. Fans out reviewers in parallel. Default trio: Product Manager, Tech Lead, Designer (Lead Frontend Engineer). Each reviews from their professional lens and emits findings tagged CRITICAL / HIGH / MEDIUM / LOW.
5. Consolidates findings via the Findings Consolidator (Haiku-backed) — dedup, group by PRD section, sort by severity, preserve reviewer attribution.
6. Triages. Findings answerable from technical context get applied to the PRD directly; findings requiring product judgment get batched into AskUserQuestion prompts (3–5 at a time).
7. Re-reviews if needed. If significant changes were applied, a fresh reviewer cycle starts. Bounded by refine_requirements.review_loops.max_cycles (default 2). Reviewers are never resumed across cycles — each cycle spawns new sub-agents to avoid context-bleed.
8. Writes the updated PRD. The output preserves the original structure and voice; changes feel like natural edits, not a rewrite. Unresolved findings (after the cycle cap) land in an Open Questions section at the end of the PRD.

#Parameters

#Reviewer roster

The default roster is the cross-functional trio you'd expect to review a PRD before build:

refine_requirements:
  reviewers:
    - agent: product-manager
      enabled: true
      focus: "Requirement clarity, acceptance criteria, scope boundaries, success metrics"
    - agent: tech-lead
      enabled: true
      focus: "Technical clarity, implicit assumptions, NFR targets, missing requirements"
    - agent: designer
      enabled: true
      focus: "UX clarity, interaction patterns, accessibility, user flow completeness"

Add specialists for project-specific concerns — e.g., a security reviewer on regulated products:

refine_requirements:
  reviewers:
    - agent: security-reviewer
      enabled: true
      focus: "Security requirements completeness, compliance gaps, threat model coverage"

A reviewer can also be a markdown prompt file in your project instead of a Synthex agent — - prompt: <path>, optionally with id:, enabled:, and focus:. Its feedback merges with the agent reviewers'. See Prompt-file reviewers.

#Severity definitions

These are tuned to PRD review, not code review — what gets flagged is ambiguity that will cause divergent interpretations downstream, not bugs:

• CRITICAL — Cannot build from this PRD. Entire feature areas undefined, fundamental contradictions, missing core requirements, target users not identified.
• HIGH — Significant ambiguity that will produce divergent implementations. Vague acceptance criteria, unclear scope, missing NFRs that affect architecture, undefined edge cases for core flows.
• MEDIUM — Improvement opportunities. Could be clearer, minor gaps, edge cases for secondary flows.
• LOW — Polish. Wording, formatting, structural improvements.

By default, the loop must address every CRITICAL and HIGH finding before terminating (min_severity_to_address: high). MEDIUM and LOW are addressed at the agent's discretion.

#When to run it

• Before /synthex:write-implementation-plan/synthex:write-implementation-plan. A vague PRD produces a vague plan. The cost of running refine-requirements first is low; the cost of replanning after a mid-build clarity blowup is high.
• After a significant PRD edit. Even a tight PRD drifts as you add scope or constraints. Re-run to catch new ambiguity.
• When a build-phase task surfaces "what does this even mean?" This is the canonical signal that an ambiguity slipped through. Loop back, refine, then re-plan affected sections.

#Common scenarios

#"Reviewers are asking questions I've already answered in CLAUDE.md"

That's a bug in the command's context-gathering, not in the reviewers. The command should read CLAUDE.md before fanning out. If the reviewers still ask, capture the questions and push them into CLAUDE.md or the specs directory — once the answer is in technical context, the next run won't escalate.

#"Reviewers raise findings the user explicitly chose against"

The command escalates those — it can't tell intentional scope-cuts from oversights. Reply to the AskUserQuestion with the rationale; the agent records the rationale in the PRD (usually in the Decisions or Out-of-scope section) so the question doesn't recur.

#"PRD is huge and the loop runs out of cycles"

Bump refine_requirements.review_loops.max_cycles in .synthex/config.yaml, or split the PRD into multiple documents and refine each independently. The "Open Questions" section at the end of the PRD names whatever remained unresolved at cycle cap.

#What it does not do

• Produce an implementation plan. Plan-writing is /synthex:write-implementation-plan/synthex:write-implementation-plan's job; refine-requirements stops at the PRD.
• Reorganize the PRD. Findings are applied as targeted edits; the existing structure and voice are preserved.
• Ask the user questions it can answer from context. If the answer is in CLAUDE.md, the specs, or the codebase, the command applies it directly — the escalation budget is reserved for genuine product judgment.

#Native looping

Pass --loop to iterate refinement until the PRD stabilizes — useful for very rough or large PRDs where one invocation doesn't converge. Iteration state lives in .synthex/loops/<loop-id>.json so the loop survives session restarts. See Native looping for the full framework contract.

Emission rule. The loop terminates when all of:

• The PRD's Open Questions section is empty (or every question is annotated Resolved with the resolution recorded).
• No ambiguity markers (?, TBD, unclear, to-be-decided) remain in the Vision, Users, Scope, Success Criteria, or Constraints sections.
• The PRD is structurally complete — every required section is populated; section summaries are coherent.
• A follow-up iteration would not add new clarifying questions.

The promise is not emitted while the agent is still asking clarifying questions or while user answers are pending. Native looping never bypasses [H] user-input gates — it just re-runs the workflow once each gate clears.

Example. Drive a rough PRD to stable across multiple cycles:

/synthex:refine-requirements --loop \
  --completion-promise "PRD_STABLE" \
  --max-iterations 12 \
  requirements_path=docs/reqs/payments-v2.md

#See also

• Native looping — the iteration framework.
• /synthex:write-implementation-plan/synthex:write-implementation-plan — the next step once the PRD is stable.
• Lifecycle — where Discover sits in the flow.
• Quality gates — the severity policy that governs this command's review loop.