ql-spec

Quantum-Loop: Spec

You are generating a formal Product Requirements Document (PRD). This document will be consumed by /quantum-loop:plan to produce machine-readable tasks for autonomous execution. Write for junior developers or AI agents -- be explicit, unambiguous, and verifiable.

Phase 0: Phase-skip check (Phase 18 / P2.4)

Before asking any clarifying question, check whether a prior /ql-spec run already converted the same design + brainstorm handoff into a PRD:

DESIGN=$(ls docs/plans/*-design.md 2>/dev/null | tail -1)
BS_HANDOFF=".handoffs/brainstorm.md"
ARGS=()
[[ -n "$DESIGN" ]]         && ARGS+=("$DESIGN")
[[ -f "$BS_HANDOFF" ]]     && ARGS+=("$BS_HANDOFF")

if bash lib/phase-skip.sh skip spec . "${ARGS[@]}"; then
  echo "[SKIP] spec is up-to-date — design + brainstorm handoff unchanged."
  bash lib/handoff.sh read spec | jq '.'
  exit 0
fi

After saving the PRD and writing .handoffs/spec.md, record the fingerprint so the next identical invocation can skip:

PRD=$(ls -t tasks/prd-*.md | head -1)
DESIGN_H=$(bash lib/phase-skip.sh hash "$DESIGN")
BS_H=$(bash lib/phase-skip.sh hash "$BS_HANDOFF")
FP=$(jq -cn --arg dp "$DESIGN" --arg dh "$DESIGN_H" --arg bp "$BS_HANDOFF" --arg bh "$BS_H" \
  '{artifacts: [{path: $dp, sha256: $dh}, {path: $bp, sha256: $bh}]}')
bash lib/phase-skip.sh record spec "$FP" . >/dev/null

Prerequisite: read prior-stage handoffs (Phase 15 / P2.3)

Before doing anything else, ingest every prior-stage handoff so decisions, rejected alternatives, and risks carry forward even across context compaction:

bash lib/handoff.sh all | jq '.'
bash lib/handoff.sh read brainstorm | jq '.'

Treat brainstorm.decided as binding (already agreed — do not re-litigate), brainstorm.rejected as closed alternatives (do not re-propose them), brainstorm.remaining as the exact backlog your PRD MUST resolve, and brainstorm.risks as mandatory §Risks entries in the PRD.

Step 1: Gather Context

1. Check for an approved design document in docs/plans/. If one exists, load it as primary context.
2. Check for existing quantum.json to understand any in-progress features.
3. Read project files (package.json, README, existing code structure) to understand the tech stack.
4. Re-read .handoffs/brainstorm.md's remaining list — it IS the starting backlog of clarifying questions.
5. N31 / v0.7.5 — grep-verify cited file paths. Before citing any file path in an AC (e.g., tests/test_X.sh, lib/Y.sh), run a grep/ls verification that the path actually exists in the codebase. If the path is being created by this PRD, annotate with [NEW] in parentheses to disambiguate. This prevents the AC-drift class of error where the spec phase hallucinates plausible-looking file paths that don't exist. Worked example: v0.7.4 US-004 cited tests/test_worktree_isolation.sh and lib/type-auditor.sh — neither existed; real names were tests/test_type_audit.sh + lib/type-audit.sh.

Step 2: Ask Clarifying Questions

Ask 2-8 clarifying questions — count adaptive to remaining ambiguity (see Question Rules below). Format each with LETTERED OPTIONS so the user can respond with shorthand like "1A, 2C, 3B, 4D, 5A".

Focus questions on areas where the design doc (if any) is ambiguous or incomplete:

• Problem/Goal: What specific problem does this solve?
• Core Functionality: What are the key user actions?
• Scope Boundaries: What should it explicitly NOT do?
• Success Criteria: How do we know it's done?
• Technical Constraints: What must it integrate with?
• Data Requirements: What data needs to be stored, fetched, or transformed?
• Error Scenarios: What happens when things go wrong?
• Priority: What is the MVP vs. nice-to-have?

Question Format

1. What is the primary goal of this feature?
   A. Improve user onboarding experience
   B. Increase task completion rate
   C. Reduce support tickets for X
   D. Other: [please specify]

2. How should priority levels be structured?
   A. Three levels (High / Medium / Low)
   B. Four levels (Critical / High / Medium / Low)
   C. Numeric (1-5 scale)
   D. Custom labels defined by user

Question Rules

• Question count is adaptive to remaining ambiguity, not a hard minimum.
• If there is no design doc and the feature is non-trivial: ask 5-8 questions.
• If a design doc exists and answers most of Phase 1's concerns: ask only what the design doc leaves ambiguous — typically 2-4 questions. Padding beyond that produces release-ops / non-goal-confirmation questions that don't belong in a PRD.
• Absolute floor: ask at least 2 questions so the user has a chance to correct course before the PRD is saved. Absolute ceiling: 8.
• Every question MUST have lettered options (A, B, C, D)
• At least one question MUST probe NON-GOALS (what it should NOT do)
• At least one question MUST probe ERROR SCENARIOS
• Do NOT ask implementation questions (framework choice, library selection)
• If a design doc exists, do NOT re-ask questions already answered there
• Count-quality test: before each question, ask yourself "is this question answered in the design doc, or would its answer materially change the PRD?" If neither, don't ask it — shallow padding is worse than fewer questions.

Step 3: Generate the PRD

Based on the user's answers, generate a PRD with ALL 9 sections below. No section may be omitted.

Section 1: Introduction/Overview

Brief description (2-3 sentences) of the feature and the problem it solves.

Section 2: Goals

Specific, measurable objectives as a bullet list. Each goal should be verifiable.

Section 3: User Stories

Format:

### US-001: [Title]
**Description:** As a [user], I want [feature] so that [benefit].

**Acceptance Criteria:**
- [ ] Specific verifiable criterion 1
- [ ] Specific verifiable criterion 2
- [ ] Typecheck/lint passes
- [ ] [UI stories only] Verify in browser

Story Sizing Rules

Each story must be completable in ONE context window (one AI agent session). Rules of thumb:

• If you cannot describe the change in 2-3 sentences, it's too big. Split it.
• One story = one database change, OR one API endpoint, OR one UI component. Not all three.

Right-sized stories (GOOD):

• Add a database column and migration
• Add a single API endpoint with validation
• Create one UI component
• Add filter logic to an existing query
• Write integration test for an endpoint

Too-large stories (BAD):

• "Build the entire priority system" (multiple stories)
• "Add priority to tasks with UI and API" (spans all layers)
• "Implement filtering, sorting, and searching" (three features)

Section 4: Functional Requirements

Numbered list with unambiguous requirements:

FR-1: The system shall store task priority as an enum ('high' | 'medium' | 'low').
FR-2: The system shall default new tasks to 'medium' priority.
FR-3: The API shall accept an optional 'priority' query parameter on GET /tasks.

Section 5: Non-Goals (Out of Scope)

Explicit list of what this feature will NOT include. This section is mandatory and must have at least 3 items.

Section 6: Design Considerations (Optional)

UI/UX requirements, mockup references, existing component reuse.

Section 7: Technical Considerations (Optional)

Constraints, dependencies, integration points, performance requirements.

Section 8: Success Metrics

Measurable outcomes (e.g., "Reduce time to find high-priority tasks by 50%").

Section 9: Open Questions

Remaining areas needing clarification. If none, state "None at this time."

Step 4: Save the PRD

Save to: tasks/prd-<feature-name>.md (kebab-case filename).

Inform the user:

"PRD saved to tasks/prd-<feature-name>.md. When you're ready to create the execution plan, run /quantum-loop:plan."

Do NOT start implementing. Do NOT create quantum.json. That is /quantum-loop:plan's job.

Acceptance Criteria Quality Standards