| name | prd-phase |
| description | Create implementation phase PRDs from pre-existing research for the telemetry agent. Translates already-complete research into focused, bounded PRDs. Use when the user says "prd-phase N" or wants to create a PRD for a specific build phase (1-7). Do NOT use for new feature discovery — use prd-create for that. |
Phase PRD Creation
Purpose
Create implementation phase PRDs for the telemetry agent by assembling content from existing research documents. All research is complete. The job is to route to the right documents, extract the right details, and produce a focused PRD.
Critical Principles
- Bounded context: Read ONLY what this phase needs. Do not read the full spec or full tech stack document. Read the specific sections listed in the routing tables below.
- No detail loss: Version numbers, API patterns, config field names, and code snippets must be copied verbatim from source documents into the PRD. Do not summarize technical details. Inline comments on type definitions (example values, explanatory phrases) are part of the verbatim contract — preserve them exactly as they appear in the source document. When the source document provides tabular or prose data but no code snippet (e.g., a pricing table without a TypeScript constant), prefer adding the snippet to the source document first so future PRDs can copy verbatim. If that is not feasible in the current session, construct the snippet faithfully from the source data and annotate it with the source location (e.g., "pricing values from Model Selection table, §2").
- Excerpt, don't just reference: Critical details (acceptance gates, API patterns, rubric rules) must be IN the PRD, not just referenced by section name.
- One phase at a time: Never create multiple phase PRDs in one session. Each phase gets a fresh context.
- TypeScript and ESM: The agent is TypeScript (
"type": "module" in package.json, native Node.js type stripping via erasableSyntaxOnly). All code samples use ESM import syntax and TypeScript interface notation. ts-morph is used for AST analysis (it handles JavaScript target files via allowJs: true).
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. Phases typically contain these subsections, though structure varies by phase:
- What Gets Built (always present)
- Acceptance Gate (always present)
- Rubric Rules That Apply (sometimes a separate subsection; sometimes embedded in "What Gets Built" prose — extract the rule IDs regardless of where they appear)
- Why This Boundary (sometimes has phase-specific variants, e.g., "Why Basic Weaver Validation Is Included Here")
- Spec Sections (table mapping to spec sections and subsections)
When an expected subsection is missing, look for the equivalent content in surrounding prose or phase-specific subsections. Extract the information regardless of structural placement.
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:
- Decision Log: Extract any decisions that changed interfaces, types, or contracts from what the design document planned
- 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):
| Section | Line | Key Subsections |
|---|
| Architecture | 55 | Coordinator+Agents 57, Coordinator API 130, Error Handling 160, Interfaces 193, Tech Stack 220, Weaver Integration 253 |
| Init Phase (Required) | 290 | What Init Does 294, Prerequisites 324 |
| Complete Workflow | 334 | (diagram through ~397) |
| How It Works | 397 | Input 399, Processing (per file) 404, Output 420, Agent Output Format 424, System Prompt Structure 438, Known Failure Modes 468, Elision Detection 484 |
| File/Directory Processing | 494 | File Revert Protocol 506, Periodic Schema Checkpoints 512 |
| What Gets Instrumented | 528 | Priority Hierarchy 530, Review Sensitivity 543, Patterns Not Covered 560 |
| What the Agent Actually Does to Code | 573 | Path 1: Auto-Instrumentation 577, Path 2: Manual Span 647, Decision: Which Path? 711 |
| Attribute Priority Chain | 721 | Schema Extension Guardrails 731 |
| Auto-Instrumentation Libraries | 745 | Why Libraries First 749, Detection Flow 755, Library Discovery 774 |
| Validation Chain | 874 | Per-File Validation (with fix loop) 878, End-of-Run Validation 983 |
| Agent Self-Instrumentation | 1020 | |
| Handling Existing Instrumentation | 1079 | |
| Schema as Source of Truth | 1097 | |
| Result Data | 1106 | Result Structure 1116, Run-Level Result 1211, PR Summary 1241, Schema Hash Tracking 1255 |
| Configuration | 1261 | What Goes Where 1312, Dependency Strategy 1352, Cost Visibility 1367 |
| Minimum Viable Schema Example | 1381 | |
| PoC Scope | 1577 | In Scope 1579, Out of Scope 1626 |
| Evaluation & Acceptance Criteria | 1642 | Two-Tier Validation Architecture 1676, Required Verification Levels 1710 |
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 docs/research/evaluation-rubric.md. The code-level rules are in Part 2: Code-Level Evaluation (line 136), organized as:
| Dimension | Location | Rules |
|---|
| Gate Checks | ~line 140 | NDS-001, NDS-002, NDS-003, API-001 |
| Non-Destructiveness | ~line 189 | NDS-004, NDS-005 |
| Coverage | ~line 218 | COV-001 through COV-006 |
| Restraint | ~line 282 | RST-001 through RST-005 |
| API-Only Dependency | ~line 337 | API-002, API-003, API-004 |
| Schema Fidelity | ~line 374 | SCH-001 through SCH-004 |
| Code Quality | ~line 422 | CDQ-001 through CDQ-007, CDQ-009, CDQ-010, CDQ-011 |
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.
Inherited gate checks (Phase 2+): The rubric defines four gate checks: NDS-001, NDS-002, NDS-003, and API-001. All have Impact: Gate. These apply to every phase regardless of whether Phase N builds them as validation stages. Always include all four in the PRD's Gate Checks table with their full definitions from the rubric. NDS-003 is implemented as a Tier 2 validation stage (Phase 2) but retains Gate impact — list it in Gate Checks, not Dimension Rules.
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:
| Phase | Section | Line | Key Types/Contracts |
|---|
| 1 | Phase 1 → Phase 2: Instrumentation Output | 29 | instrumentFile interface, InstrumentationOutput type |
| 2 | Phase 2 → Phase 3: Validation Results | 84 | validateFile interface, ValidationResult/CheckResult types, ValidateFileInput |
| 3 | Phase 3 → Phase 4: File-Level Result | 151 | instrumentWithRetry interface, FileResult evolution, schema re-resolution |
| 4 | Phase 4 → Phase 5/6: Run-Level Result | 211 | coordinate interface, RunResult type, CoordinatorCallbacks |
| 5 | Phase 5: Schema Integration Extensions | 254 | Schema integration extensions to RunResult |
| 6 | Phase 6: Interface Layer | 262 | CostCeiling, CoordinatorCallbacks (wiring focus) |
| 7 | Phase 7: Deliverables | 290 | RunResult consumption for git/PR, advisoryAnnotations flow |
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 from the tech stack evaluation — all TypeScript, ESM imports. The
tech-stack-by-phase.md routing table identifies which snippets must appear for each phase under "Key Code Snippets" headings.
- If the tech stack evaluation has prose/tabular data for a pattern but no code snippet, check whether
tech-stack-by-phase.md provides one. If neither document has a snippet, flag the gap for the user rather than silently constructing one.
- 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-10 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
- Add rows for cross-cutting sections read in Step 2 (e.g., "Two-Tier Validation Architecture", "Validation Chain Types") when they contain type definitions or architecture directly needed for implementation and aren't already in the phasing document's table
- Add rows for spec sections not in the phasing document's table that the implementing AI needs for this phase's core deliverables — particularly sections that define rendering formats, output structures, or classification systems consumed by the phase (e.g., Phase 7 needs "Priority Hierarchy" and "Review Sensitivity" to render the PR summary, even though the phasing document didn't list them)
Step 5: Create GitHub Issue and PRD File
Follow the same workflow as /prd-create:
-
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
-
Create PRD file at prds/[issue-id]-phase-N-[phase-name].md
-
Update GitHub Issue with PRD link
-
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:
Source Documents
| Document | Path | Purpose |
|---|
| Implementation Phasing | docs/specs/research/implementation-phasing.md | Phase definitions, spec section maps, cross-cutting architecture |
| Telemetry Agent Spec | docs/specs/telemetry-agent-spec-v3.9.md | Source of truth for what to build |
| Tech Stack Evaluation | docs/architecture/tech-stack-evaluation.md | Version numbers, API patterns, library choices |
| Evaluation Rubric | docs/research/evaluation-rubric.md | Full rule definitions for acceptance criteria |
| Architectural Recommendations | docs/architecture/recommendations.md | Preserve/change verdicts, evidence base |
| Design Document | docs/architecture/design-document.md | Interface contracts, module organization, decision register |
| Tech Stack by Phase | references/tech-stack-by-phase.md (skill-bundled) | Routing table: which tech stack sections per phase |
| Phase PRD Template | references/phase-prd-template.md (skill-bundled) | Output template |
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 in technical sections. The implementing AI needs what to build, not why the last attempt failed. Brief evaluation references in "Why This Phase Exists" are acceptable as motivation for specific requirements (e.g., explaining why the acceptance gate requires callbacks to actually fire). Keep evaluation context out of the tech stack, rubric rules, milestones, and spec reference sections.
- 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/
