docs(prd): improve Phase 11 Metadata Extraction PRD based on review feedback - #162

Reviewing files that changed from the base of the PR and between c954e71 and acebdf5.

• .claude/commands/destroy-prd.md
• docs/project/PRD/archived/PRD-phase-10-typescript-extraction.md
• docs/project/PRD/notstarted/PRD-phase-11-metadata-extraction.md

• GitHub Check: Cloudflare Pages

.claude/commands/destroy-prd.md (5)

1-18: LGTM: Clear usage and strong instructions.

The command definition is unambiguous, and the instructions appropriately set expectations for a comprehensive, zero-tolerance analysis. The directive to "find everything" aligns with the goal of detecting issues before AI implementation.

---

25-62: LGTM: Comprehensive INCOSE ambiguity detection.

The ambiguity scan categories are well-chosen and comprehensive. The requirement to provide exact quotes, locations, why it's problematic, and suggested rewrites ensures actionable feedback. Marking escape clauses as "always CRITICAL" is appropriate for autonomous AI implementation.

---

64-138: LGTM: Well-structured analysis checklist.

The 8-section checklist systematically addresses the critical aspects of PRD quality for AI implementation:

• Architectural integration (dependencies, interfaces, handoffs)
• Logical consistency (preconditions, circular dependencies)
• Implicit assumptions (undefined concepts, assumed knowledge)
• Edge cases and error handling
• Success criteria verifiability
• AI implementation feasibility (context window, concrete details)
• Completeness gaps

Each section asks specific, actionable questions.

---

142-164: LGTM: Clear output format with severity classification.

The standardized issue template with severity levels (Critical/Medium/Minor) ensures consistent reporting. The inclusion of "AI failure mode" is particularly valuable—it forces the reviewer to think about concrete implementation impacts (guess wrong, ask question, inconsistent output, blocked).

---

167-177: LGTM: Comprehensive final summary structure.

The 5-part summary ensures both breadth (total counts, zero-issue sections) and depth (top 5 severe, specific questions, cross-cutting recommendations). The requirement to list "Sections with zero issues" confirms complete coverage. The final directive reinforces the zero-tolerance analysis approach.

docs/project/PRD/notstarted/PRD-phase-11-metadata-extraction.md (10)

9-23: LGTM: Clear and specific problem statement.

The problem is well-defined with a structured table listing missing required fields per component type. The impact is concrete: draft components cannot become valid Riviere graph components, preventing architecture visualizations. The additional requirement for PR-scoped component understanding is clearly stated.

---

27-57: LGTM: Clear, actionable design principles.

The 11 design principles are concrete and unambiguous:

• Core Extraction Principles establish source-of-truth extraction, schema alignment, config validation, fail-fast behavior, and strictness control
• Enforcement Principles mandate enforcement mechanisms with a clear preference for compiler over linter
• Flexibility Principles balance strictness with support for diverse codebases

No vague terms or escape clauses detected. Each principle is implementable.

---

59-112: LGTM: Well-defined pipeline architecture.

The pipeline architecture section is comprehensive and unambiguous:

• Phase integration clearly specifies inputs (DraftComponent from Phase 10) and outputs (enriched components)
• Two workflows with concrete executable commands
• Use cases for two-pass workflow are specific (incremental adoption, AI-assisted completion, debugging)
• Package locations table provides clear paths and responsibilities
• Source of truth explicitly identified (riviere.schema.json)

---

117-507: LGTM: Highly detailed extraction specifications.

Sections 3.1-3.5 provide comprehensive, unambiguous specifications:

• Config DSL examples are complete, runnable YAML with class-level and method-level extraction patterns
• Output format includes full JSON examples for both strict and lenient modes
• CLI behavior specifies exact flags, exit codes (0-3), and error message format
• Extraction rules define a closed list with explicit return types, literal value constraints, and transform execution order
• Edge case behaviors documented in a table with strict/lenient mode outcomes
• Five complete code examples with matching extraction configs

This level of detail supports autonomous implementation.

---

509-646: LGTM: Complete specifications for conventions, PR extraction, AI scanner, and demo refactor.

Sections 3.6-3.9 maintain the same level of concrete detail:

• Conventions package includes complete TypeScript interface definitions and 4 named ESLint rules
• PR extraction specifies exact git commands, edge case error codes, and markdown output format
• AI scanner has measurable acceptance criteria (config validates, produces non-empty results, ESLint syntactically valid) and specific test methodology
• Demo app refactoring has 4 specific goals (interfaces, static properties, 100% extraction, 100% enforcement)

All specifications are implementable without additional clarification.

---

650-663: LGTM: Clear exclusions with specific behaviors.

The exclusions table explicitly defines what's NOT being built and what happens when each scenario is encountered. This prevents scope creep and sets clear expectations. Examples:

• "Non-TypeScript files silently skipped" (multi-language)
• "Each run is fresh. No caching between runs" (incremental caching)
• Specific warning message for cross-file value resolution

This is a strong boundary-setting practice.

---

667-681: LGTM: All success criteria are verifiable.

All 11 success criteria follow best practices for verifiability:

• Testable with specific commands (e.g., pnpm nx test, riviere extract --dry-run, pnpm lint)
• File existence checks (e.g., file exists at docs/ai-prompts/codebase-scanner.md)
• Observable outputs (e.g., "zero _missing arrays", "produces non-empty results")
• Countable artifacts (e.g., "5 interfaces and 4 ESLint rules", "all 15 rules")

No criteria rely solely on subjective review. This enables autonomous verification.

---

685-697: LGTM: All open questions resolved with specific answers.

All 6 questions have been resolved with concrete, implementable answers:

• Partial metadata → Strict by default, --allow-incomplete for lenient with _missing tracking
• Config validation → Load-time validation with clear error messages
• Inheritance chains → ts-morph walks inheritance chain
• notUsed → Suppresses validation entirely for that component type
• Re-exported interfaces → Name-based matching regardless of import path
• Multiple interfaces → Uses interface specified in the rule

No ambiguity or deferred decisions.

---

960-1037: LGTM: Clear dependencies, reference material, and parallelization plan.

The final sections are well-organized:

• Dependencies section clearly states Phase 10 dependency and Phase 12 blocking, with a table of package paths showing which packages are modified
• Reference section clarifies terminology (route → path mapping) and provides metadata tables per component type
• Parallelization section identifies 4 independent work streams with an ASCII diagram showing convergence points and a table explaining why tracks are independent

This supports parallel development and clarifies integration points.

---

701-956: Milestones are well-structured and mostly verifiable.

The 6 milestones plus research task provide a clear implementation path:

• Each deliverable has specific acceptance criteria and verification methods
• Most verification is objective (tests pass, commands execute, files exist, counts match)
• Deliverables are appropriately scoped for incremental progress

Minor observation: A few deliverables use subjective acceptance criteria:

• M1.D1.1: "ADR reviewed and approved"
• M4.D4.1: "Developer understands usage"
• M6.D6.1-D6.4: "Review docs" (appears 4 times)

These are paired with file existence checks, mitigating the subjectivity, but consider adding more objective criteria where possible (e.g., "Docs include X examples and Y commands").

⛔ Skipped due to learnings

Learnt from: NTCoding
Repo: NTCoding/living-architecture PR: 120
File: docs/workflow/parallel-workflow.md:1-555
Timestamp: 2026-01-10T19:16:56.186Z
Learning: Investigation task documents (like `docs/workflow/parallel-workflow.md`) should focus on design and workflow specification rather than implementation concerns such as phased rollout plans, success metrics, and rollout risk mitigation. These operational details are addressed later when creating tasks to build the workflow.

Learnt from: CR
Repo: NTCoding/living-architecture PR: 0
File: docs/architecture/overview.md:0-0
Timestamp: 2026-01-08T22:20:13.250Z
Learning: Applies to docs/architecture/**/*extract*.{json,ts} : Define extraction configuration using the JSON Schema from `living-architecture/riviere-extract-config` DSL