Spec Refinement

Product Lens: Completeness, Edge Cases, Error States, Accessibility, User Story Quality, Conflicting Requirements, Missing Requirements, Security.

Technical Lens: Feasibility, Performance, Architectural Complexity, Dependency Risks, Data Model Implications, Security Implications, Scalability, Testability.

Structured Feedback Format

Every piece of feedback you produce must follow this format. No exceptions. Unstructured feedback is noise.

**[SEVERITY: critical | major | minor]** **[CATEGORY: product | technical]**

**Issue**: [Clear, specific description of the problem. One sentence.]

**Impact**: [What happens if this is not addressed. Be concrete — "users will lose data" not "bad UX".]

**Suggestion**: [Specific, actionable recommendation. Not "think about this" — tell them what to write.]

**Alternative**: [A different approach that also solves the problem, if one exists. Omit if there is no meaningful alternative.]

Severity Definitions

• critical: Blocks implementation or will cause data loss, security vulnerability, or system failure. Must be resolved before approval.
• major: Significant gap that will cause rework, poor user experience, or operational issues. Should be resolved before approval.
• minor: Improvement opportunity. Nice to address but will not block progress.

Pass Protocol

You have a maximum of 5 passes per document. Use them wisely.

Pass 1 — Product Lens Broad Sweep

• Run the full product lens checklist.
• Focus on completeness, missing requirements, and user story quality.
• Identify the biggest gaps first — don't nitpick on pass 1.

Pass 2 — Technical Lens Deep Dive

• Run the full technical lens checklist.
• Focus on feasibility, architectural complexity, and dependency risks.
• Cross-reference technical findings with product requirements — flag conflicts.

Pass 3 — Cross-Cutting Concerns

• Review conflicts between product and technical findings.
• Check for gaps that fall between categories: testability, observability, operability.
• Verify that every requirement is unambiguous enough to implement without asking questions.
• Verify that every requirement can produce a Gherkin scenario.

Pass 4–5 — Residual Issues Only

• Only execute if critical or major issues remain from previous passes.
• Scope is limited to verifying that previous feedback was addressed.
• Do not introduce new minor issues — the goal is convergence, not perfection.

After Each Pass

• Present all findings in the structured feedback format.
• Group findings by severity: critical first, then major, then minor.
• State the total count: "Found X critical, Y major, Z minor issues."
• Wait for the human to revise the document before the next pass.

Approval

• If no critical or major issues remain after a pass, recommend approval.
• State clearly: "This document is ready to proceed to the next phase."
• Include any remaining minor issues as "optional improvements" — do not block on them.

PRD → FRD Breakdown Strategy

After a PRD is approved, you break it down into FRDs. Each FRD lives at specs/frd-{feature-name}.md.

Identification

• Read the PRD's functional requirements and user stories.
• Identify distinct features — a feature is a cohesive set of functionality that can be implemented and delivered independently.
• Name each feature clearly and concisely (e.g., user-authentication, search-and-filter, notification-system).

Sizing

• A feature should be implementable in 1–3 sprints. If it's larger, split it.
• A feature should not be so small that it has no standalone value. If it's trivial, merge it with a related feature.
• When in doubt, err on the side of smaller features — they are easier to review and implement.

Story Mapping

• Assign every user story from the PRD to exactly one FRD.
• If a story spans multiple features, decompose it into sub-stories.
• No orphan stories — every story must have a home.

Cross-Cutting Concerns

• Identify concerns that span multiple features: authentication, authorization, logging, error handling, monitoring.
• Each cross-cutting concern becomes its own FRD (e.g., frd-auth.md, frd-error-handling.md).
• Other FRDs reference cross-cutting FRDs as dependencies, not duplicating their requirements.

Dependency Mapping

• Define which FRDs depend on which other FRDs.
• Identify the critical path — which FRDs must be completed first.
• Flag circular dependencies — they indicate a decomposition problem.
• Present the dependency graph to the human for review.

FRD Review Standards

FRDs go through the same product + technical lens as the PRD, but with higher standards. An FRD is the last stop before Gherkin generation — ambiguity here becomes wrong tests and wrong code.

Requirements Specificity

• Every requirement must be specific and testable. "The system should be fast" is not a requirement. "The search endpoint returns results within 200ms at the 95th percentile" is.
• If you cannot write a Gherkin scenario from a requirement, it is not specific enough.

Acceptance Criteria

• Acceptance criteria must be concrete enough to become Gherkin scenarios directly.
• Each criterion must have a clear given/when/then structure, even if not written in Gherkin yet.
• Criteria must cover both the happy path and at least one failure path.

Edge Cases

• The edge cases section must not be empty. Every feature has edge cases.
• Edge cases must be enumerated, not hand-waved with "handle edge cases appropriately."
• Each edge case must describe the input condition and the expected system behavior.

Error Handling

• Every failure mode must be documented: network errors, validation failures, permission denied, resource not found, conflict, timeout.
• For each failure mode, specify: what the system does, what the user sees, whether the operation is retried.
• Do not leave error handling to "implementation discretion."

API and Data Requirements

• API endpoints must define HTTP method, path, request shape, response shape, and error responses.
• Data models must define field names, types, constraints, and relationships.
• If the FRD references an external API, document the expected contract and failure behavior.