Prd Phase

Process

Step 1: Identify the Phase

Parse the phase number (1-7) from the user's command.

Step 2: Read the Phase Definition

Read the specific phase section from docs/specs/research/implementation-phasing.md. Each phase contains:

• What Gets Built
• Acceptance Gate
• Rubric Rules That Apply
• Why This Boundary
• Spec Sections (table mapping to spec sections and subsections)

Also read these cross-cutting sections (they apply to every phase):

• "Two-Tier Validation Architecture" section
• "Cross-Cutting: The DX Principle" section

Step 2b: Read Previous Phase PRD (Phase 2+ only)

Skip this step for Phase 1 — it has no predecessor.

For Phase 2+, read the previous phase's PRD file (prds/[id]-phase-[N-1]-*.md). Focus on:

1. Decision Log: Extract any decisions that changed interfaces, types, or contracts from what the design document planned
2. Interface changes: Compare the previous phase's delivered interface with what docs/architecture/design-document.md defines for the Phase N-1 → Phase N boundary

Include deviations in the new PRD's Dependencies section as:

Phase N-1 delivered [interface/type] (with these modifications from plan: [list changes]).

If the previous phase's decision log and design document agree (no deviations), note: "Phase N-1 delivered interfaces as planned in the design document."

Step 3: Read Source Documents (Routing)

Read ONLY the sections relevant to this phase.

3a. Spec Sections

The phase definition contains a "Spec Sections" table. For each row:

• Full -> read the entire section from docs/specs/telemetry-agent-spec-v3.9.md
• Subsection only -> read only the named subsection
• Fields only -> extract just the named configuration fields
• Row only -> extract just the named row from the Technology Stack table

Note: The spec was renamed from v3.5.md → v3.6.md → v3.7.md → v3.8.md → v3.9.md as content versions evolved.

Spec section landmarks (line numbers for the 1,791-line spec):

3b. Tech Stack Sections

Read references/tech-stack-by-phase.md (bundled with this skill) to find which sections of docs/architecture/tech-stack-evaluation.md to read for this phase. Extract:

• Version numbers (exact)
• API patterns (code snippets, verbatim)
• Caveats and limitations
• Recommendation summaries

3c. Rubric Rules

The phase definition lists rubric rule IDs (e.g., NDS-001, CDQ-003). Look up each rule's full definition in research/evaluation-rubric.md. The code-level rules are in Part 2: Code-Level Evaluation (line 136), organized as:

For each rule, extract: Rule ID, name, impact level, evaluation scope, full description including evaluation method, and automation classification (summary at ~line 514).

For Phase 2+, classify rules as Tier 1 (structural/blocking) vs Tier 2 (semantic/blocking or advisory) using the "Two-Tier Validation Architecture" section of implementation-phasing.md.

3d. Architectural Context (if needed)

Read relevant sections of docs/architecture/recommendations.md:

• Phases 1-3: "Fix Loop Feedback Quality" subsection
• Phase 2: "Two-Tier Validation (New Architecture)" section
• Phases 4-7: "DX and Error Handling Architecture" section
• All phases: Summary table at end for quick reference

3e. Design Document

Read relevant sections of docs/architecture/design-document.md. This document defines cross-phase interface contracts, module organization, and a consolidated decision register.

All phases — read these sections:

• Module Organization (line 312): Directory Structure (314), Module Dependency Rules (337)
• Phase-to-Module Mapping (line 360): which modules get built in which phase
• Consolidated Decision Register (line 376): design decisions that may affect implementation

Phase-specific interface contracts:

Also read the Interface Contract Summary table (line 294) for a quick reference of all contracts.

Extract from the design document into the PRD:

• The interface contract relevant to this phase (input types, output types, function signature)
• Any decision register entries that affect this phase's implementation
• The module directory paths this phase creates (from the Phase-to-Module Mapping)

Step 4: Assemble the PRD

Read references/phase-prd-template.md (bundled with this skill) for the output template.

Fill in each section using content gathered in Steps 2-3. Key rules:

Tech Stack section:

• Copy version numbers exactly (e.g., "Vitest 4.0.18", not "latest")
• Copy API code snippets verbatim — all TypeScript, ESM imports
• Include caveats that affect THIS phase
• Include only entries relevant to this phase

Rubric Rules section:

• Include the full rule definition, not just the ID
• Group by Gate vs Dimension
• Note which are Tier 1 vs Tier 2 (for Phase 2+)
• Include impact level and automation classification

Acceptance Gate section:

• Copy the gate verbatim from the phasing document
• Add specific, testable verification steps
• Map each gate criterion to the rubric rules that verify it

Milestones:

• Define 5-8 milestones that build toward the acceptance gate incrementally
• Each milestone should be independently testable
• Final milestone: "Acceptance gate passes end-to-end"
• Include a milestone for the DX cross-cutting requirement specific to this phase
• Use the Phase-to-Module Mapping from the design document (Step 3e) to identify which module directories this phase creates — milestones should align with the module structure
• Where a milestone directly satisfies a rubric rule, note the rule ID (e.g., "Tier 1 syntax check works → NDS-001"). Not every milestone maps to a rubric rule — Phase 1 milestones about prompt engineering and file I/O have no clean rubric connection, and stretching for one adds noise. Phase 2 (validation chain) maps naturally. Include the mapping where it's real; omit it where it isn't.

Spec Reference section:

• Reproduce the spec section map table from the phasing document
• Add line number ranges from the landmarks table above

Step 5: Create GitHub Issue and PRD File

Follow the same workflow as /prd-create:

1. Create GitHub Issue with label "PRD":

   ## PRD: Phase N — [Phase Name]
   
   **Problem**: Implementation phase N of the telemetry agent — [what gets built]
   
   **Solution**: [1-2 sentence summary from phasing document]
   
   **Detailed PRD**: Will be added after PRD file creation
   
   **Priority**: High
   

2. Create PRD file at prds/[issue-id]-phase-N-[phase-name].md

3. Update GitHub Issue with PRD link

4. Commit with [skip ci] flag:

   docs(prd-[issue-id]): create Phase N PRD — [phase-name] [skip ci]
   

Step 6: Post-Creation Verification

Before presenting the PRD to the user, verify:

• Every rubric rule ID listed in the phasing document appears with its full definition
• Every spec section from the phase's spec section map is referenced with line numbers
• Tech stack version numbers are exact (not "latest" or "current")
• API code snippets are present and use TypeScript ESM syntax
• The acceptance gate is copied verbatim from the phasing document
• The DX cross-cutting requirement for this phase is included
• No content from other phases leaked in
• Milestones build incrementally toward the acceptance gate
• All agent code samples are TypeScript; target file examples remain JavaScript

Source Documents

Important Notes

• One phase per session. Multiple phase PRDs in one context risks detail loss.
• The spec is the source of truth. If the phasing document and spec disagree, the spec wins. Flag the discrepancy for the user.
• Don't include evaluation findings. The implementing AI needs what to build, not why the last attempt failed.
• Don't include rejected alternatives. No LangGraph comparisons, no Babel evaluations.
• Trust the routing tables. Don't add "extra context that might be helpful."
• TypeScript for agent code, JavaScript for target files. The agent code is TypeScript with ESM modules (native type stripping, erasableSyntaxOnly). ts-morph handles JavaScript target files via allowJs: true. Agent code samples use TypeScript; target file examples remain JavaScript.

Note: If any gh command fails with "command not found", inform the user that GitHub CLI is required: https://cli.github.com/