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.