prd-pilot

name

prd-pilot

description

PRD-to-code conflict detection. Activate when: (1) user asks to audit/check/validate a PRD against existing code, (2) user says "prd:audit", "审 PRD", "需求冲突检测", "PRD 审查", (3) user provides a PRD document and asks if it conflicts with current implementation, (4) before Spec Coding to validate requirements feasibility. Output: structured audit report with CONFLICT/WARNING/GAP/PASS findings, each backed by code evidence (file path + line numbers). NOT for: plan generation, code review, writing PRDs, or tasks better handled by spec-kit / Superpowers.

PRD Pilot — Code-Requirement Cross Analyzer

Analyze a PRD document against a project codebase to detect conflicts, gaps, and implementation risks before coding begins. Output a structured audit report with evidence-backed findings.

Diff Mode (Fast Path for Iterative PRD Changes)

Use Diff Mode when:

• PRD has been updated since last audit
• You have a previous audit report and want to re-audit only changed sections
• User provides prd:audit --diff <old.md> <new.md> command
• User says: "re-audit changed sections", "incremental audit", "only verify updates"

Why Diff Mode matters: PRD audits are expensive. Diff Mode detects content changes (via fingerprinting), then re-scans only modified requirements, inheriting PASS/GAP findings from unchanged sections. On typical 5-10% PRD changes, this reduces audit time by 85-90%.

Diff Mode Workflow

Step C1 — Locate Cache

After reading PRD in Stage 1, immediately check for cached audit:

For Feishu documents (with MCP):

1. Extract doc_id from the PRD URL (format: https://xxx.feishu.cn/docx/{doc_id})
2. Call mcp__feishu-docs__search-doc with empty query to retrieve document metadata
3. Locate the document entry matching doc_id and extract update_time and create_time
4. Search .prd-pilot/prd/ for cache file with matching doc_id in frontmatter
5. Example match: .prd-pilot/prd/user-login-v1.md has doc_id: xxxxxx + feishu_update_time: 2026-04-10 → cache found

For local markdown files:

• Search for {filename}-cached.md in .prd-pilot/prd/
• Example: audit_prd.md → look for audit_prd-cached.md

If no cache found → skip Diff Mode, execute full Phase 1, then run Step C4 (cache write)

Note: Feishu MCP integration provides authoritative update_time from the server, enabling precise version tracking without relying on content inspection alone.

Step C2 — Content Fingerprint Verification + Cache Staleness Check

Cache Staleness Pre-Check (before fingerprint comparison):

Even if fingerprint matches, verify cache is still valid:

**Cache Staleness Check (Executable Commands):**

```bash
# Rule 1: Check cache age
CACHE_FILE=".prd-pilot/audit-YYYY-MM-DD.md"
CACHE_AGE_DAYS=$(( ($(date +%s) - $(stat -f%m "$CACHE_FILE" 2>/dev/null)) / 86400 ))

if [ "$CACHE_AGE_DAYS" -gt 30 ]; then
  # Rule 2: Check if >20% of code files changed since cache
  TOTAL_CODE_FILES=$(find {project_dir} -type f \( -name "*.go" -o -name "*.ts" -o -name "*.py" -o -name "*.java" -o -name "*.js" \) | wc -l)
  
  CHANGED_FILES=$(find {project_dir} -type f \( -name "*.go" -o -name "*.ts" -o -name "*.py" -o -name "*.java" -o -name "*.js" \) -newer "$CACHE_FILE" | wc -l)
  
  CHANGE_PERCENTAGE=$(( (CHANGED_FILES * 100) / TOTAL_CODE_FILES ))
  
  if [ "$CHANGE_PERCENTAGE" -gt 20 ]; then
    echo "⚠️ Cache is $CACHE_AGE_DAYS days old and $CHANGE_PERCENTAGE% of code changed."
    echo "Consider running full audit for accuracy."
    # Show user prompt: "Run full audit" or "Use cache anyway"
  fi
fi

Logic:

1. Check if cache file age > 30 days
2. If yes, count how many code files modified -newer than cache file
3. If > 20% changed, warn user and offer choice

If staleness detected, show user prompt:

"⚠️ Cache is {n} days old and {change_percentage}% of code has changed since then.

Previous audit conclusions may be outdated. Consider running full audit for accuracy.

Options: ['Run full audit', 'Use cache anyway']"

**SKIP fingerprint comparison if:**
- Cache is > 30 days old AND > 20% code files changed since cache date
- User chooses "Run full audit" (bypass Diff Mode entirely)

**PROCEED to fingerprint comparison if:**
- Cache is fresh (< 30 days old), OR
- Code changes < 20%, OR
- User chooses "Use cache anyway"

---

**For Feishu documents (preferred):**

Use authoritative server-side metadata for fingerprinting:

```python
# Feishu API provides precise update_time
feishu_fingerprint = f"{feishu_metadata.update_time}_{doc_id}"
# Example: "2026-04-10T15:30:00+08:00_GSYawcl6jiKe0skYjxvcrt9qnbh"

For local files (fallback):

Compute client-side content fingerprint with Unicode normalization (for Chinese/multi-byte support):

import unicodedata

def compute_fingerprint(content: str) -> str:
    """
    Content fingerprint with three-segment sampling for comprehensive change detection.
    
    Takes prefix, middle, and suffix to detect changes anywhere in the document,
    not just at head/tail.
    """
    import unicodedata
    
    # Normalize to NFD (Compatibility Decomposed) for stable hashing
    normalized = unicodedata.normalize('NFD', content)
    
    # Strip whitespace fluctuations (extra newlines, indentation)
    normalized = '\n'.join(line.strip() for line in normalized.split('\n') if line.strip())
    
    # Three-segment fingerprinting for better coverage
    # prefix + middle + suffix ensures changes anywhere in document are detected
    mid = len(normalized) // 2
    fingerprint = (
        f"{len(normalized)}_"
        f"{normalized[:80]}_"
        f"{normalized[mid:mid+80]}_"
        f"{normalized[-80:]}"
    )
    
    return fingerprint

# Example:
# content = "用户登录功能 —— 用户需要能通过手机号和密码登录系统..."
# fingerprint = compute_fingerprint(content)
# Result: "156_用户登录功能 —— 用户需要能通过手机号和密码登录系统_...登录失败则提示错误信息"

Comparison logic:

Compare computed fingerprint with cached content_fingerprint:

• Match → PRD unchanged. Display to user: "No changes detected in {title} (cached {cached_at}). Reusing previous audit report." Then output cached report and exit.
• Mismatch → PRD updated. Proceed to Step C3.

Fingerprinting precision: Feishu API timestamps are 100% accurate vs. content-based hashing (~85% reliable for small changes).

Step C3 — User Confirmation

Ask user which audit path to take:

Detected update in "{title}" (last cached: {cached_at}).

Options:
1. "Yes, audit changes only (faster)"        → Run Steps D1-D3 (Diff Mode)
2. "No, re-scan everything"                  → Run full Phase 1, then Step C4

Wait for user selection before proceeding.

Step C4 — Write/Update Cache

Execution timing: After every full Phase 1 audit (not after Diff Mode audits)

Cache file structure:

Create or update .prd-pilot/prd/{title}-v{n}.md:

---
source_type: feishu_doc | local_file
source_url: https://xxx.feishu.cn/docx/xxxxxx        # (only for Feishu)
doc_id: xxxxxx                                        # (only for Feishu; used for matching)
title: User Login Feature PRD
version: 1                                            # Increment on each full audit
cached_at: 2026-04-11

# Feishu API metadata (populated only when source_type=feishu_doc)
feishu_update_time: "2026-04-10T15:30:00+08:00"      # Server timestamp (used for C2 comparison)
feishu_created_time: "2026-04-10T10:00:00+08:00"     # Document creation time
feishu_owner: "露娜-macbook"                          # Document owner
feishu_doc_type: "DOCX"                               # Document type

# Content fingerprint (used for local files in C2 comparison)
# Format: len_prefix80_middle80_suffix80 (three-segment for comprehensive change detection)
content_fingerprint: "15234_用户登录功能。用户需要能够通过手机号和密码登录系统_...登录失败则返回错误信息"

last_audit: ../.prd-pilot/audit-2026-04-10.md        # Path to previous Stage 5 audit report
---

{full PRD content here}

Cache Field Meanings:

• For Feishu docs: feishu_update_time is compared in Step C2
• For local files: content_fingerprint is compared in Step C2
• Both: cached_at used for staleness check (> 30 days)

Version increment logic:

• First cache: version: 1
• Each subsequent full audit: version += 1
• Diff Mode audits: do NOT increment version or update cache

Manual Triggers for Diff Mode

Users can trigger Diff Mode explicitly without waiting for auto-detection:

Command syntax:

prd:audit --diff <old.md> <new.md>

User phrases:

• "Re-audit only the changed requirements"
• "Incremental audit"
• "Check what's new in the updated PRD"

---

Diff Steps (D1–D3)

Step D1 — Parse Diff

Compare current PRD content with cached content. Classify each requirement:

Classification	Definition	Action
REVALIDATE	New requirement or modified text	Must re-scan code in Stage 3
INHERIT	Unchanged requirement text	Reuse finding from last_audit report; skip code scan
RETIRE	Requirement deleted from PRD	Check for DANGLING_CODE; mark as historical

Diff extraction approach:

1. Parse both cached and current PRD into requirement lists (same structure as Stage 1)
2. Match by requirement ID or semantic similarity (if IDs change)
3. For each match, compare text:
   • If text_changed → REVALIDATE
   • If text_identical → INHERIT
   • If no_match_in_current → RETIRE

RETIRE handling: Dangling Code Detection

For each RETIRE requirement:

1. Retrieve code evidence from previous audit report (e.g., "code_file: auth.ts:45-60")
2. Extract keywords from the old requirement
3. Run quick check: timeout 60s rg -l "{keywords}" {project_dir}
4. If code still found:
   • Flag as ⚠️ DANGLING_CODE in new report
   • Reasoning: "Feature requirement removed from PRD but code still present — potential technical debt"
   • Recommendation: "Review and either: (a) add requirement back to PRD if feature is still needed, or (b) remove code from codebase"
5. If code not found:
   • Mark as CLEAN_RETIRE (code already removed)
   • No action needed

Step D2 — Map to Previous Findings

Load the last_audit report (from cache frontmatter). For each requirement:

• REVALIDATE → Note the old finding, but plan to re-scan
• INHERIT → Copy the old finding directly to new report (no code re-scan needed)
• RETIRE → Archive the old finding in a "Historical" section

Example:

Previous audit: R1 "User login by email" → PASS (finding: session.ts:45-60)
Current PRD: R1 text unchanged → INHERIT → Copy PASS to new report

Previous audit: R2 "Rate limit 3/min" → CONFLICT (finding: no rate limit code)
Current PRD: R2 text modified to "Rate limit 5/min" → REVALIDATE → Re-scan code

Step D3 — Partial Code Scan

Execute Stage 3 & 4 only for REVALIDATE requirements. For INHERIT requirements, skip Stage 3 scanning entirely.

Scan budget for Diff Mode:

- Unchanged requirements (INHERIT):  0 scans (reuse findings)
- Modified requirements (REVALIDATE): Standard Stage 3 scan per requirement
- RETIRE requirements:                0 scans (archived)

Example savings:
  Full PRD: 10 requirements, ~300 LOC to scan per req = 3000 LOC total
  Diff (10% change): 1 REVALIDATE req + 9 INHERIT
                     ~300 LOC to scan + 0 (reused)
                     = 90% reduction

Output: Incremental Audit Report

Generate Stage 5 report with:

• CONFLICT/WARNING/GAP/PASS findings from REVALIDATE scanning
• PASS findings inherited from previous audit (marked as [inherited])
• Historical RETIRE findings in appendix
• Summary callout: "Incremental audit: 1 requirement changed, 9 inherited"

---

Cache Directory Structure

.prd-pilot/
├── prd/                                              # Cache directory
│   ├── user-login-v1.md                             # Cached: Feishu doc
│   ├── user-login-v2.md                             # Cached: v2 (newer)
│   ├── feature-spec-cached.md                       # Cached: local file
│   └── README.md                                     # (optional) cache guide
├── audit-2026-04-10.md                              # Full audit report
├── audit-2026-04-11.md                              # Full audit report (newer)
└── code-map-2026-04-10.md                           # Generated code map (Stage 2.8)

Performance Impact

Scenario	Audit Time	vs. Full Scan	Cache Hit Rate
First audit (no cache)	Full scan	—	0%
Cache hit + no changes	~30ms	↓98%	100%
Cache hit + 10% PRD changed	~15-20% of full scan	↓80-85%	90% INHERIT
Manual --diff specified	Only changed sections	↓70-90%	N/A
Large project (>10k LOC) + 5% change	~2-3 min	↓87%	95% INHERIT

---

Diff Mode Activation Rules

Diff Mode auto-activates when ALL conditions true:

1. Cache found (Step C1 success)

2. PRD content changed (Step C2):

   • Feishu documents: feishu_update_time in cached file differs from current update_time (from MCP search-doc API)
   • Local files: content_fingerprint mismatch (three-segment fingerprinting)

3. User confirms "audit changes only" (Step C3)

Fallback conditions:

• If no cache found → Skip to Phase 1 (full audit)
• If cache staleness check fails (> 30 days + > 20% code changed) → Offer user choice
• User explicitly calls prd:audit --diff → Force Diff Mode regardless

Inputs

Two required inputs:

1. PRD document: Local markdown file path (e.g., ./docs/prd-v1.md) or Feishu doc URL
2. Project directory: Local codebase root (defaults to current working directory)

If user provides a Feishu doc URL, follow this confirmation protocol before extracting content:

1. Call mcp__feishu-docs__fetch-doc (Feishu MCP) with the document ID extracted from the URL, but only read the first ~200 characters to obtain the document title / opening line.
2. Use AskUserQuestion:
   • Question: "检测到飞书文档「{document_title}」，确认是该文档吗？"
   • Options: ["确认，继续执行", "URL 有误，我来重新提供"]
3. Wait for user's selection before proceeding.
4. Only after confirmation: extract full content, save to a temp file, and proceed.

🔄 Diff Mode Check (After Content Confirmed, Before Stage 1)

CRITICAL TIMING: Execute Diff Mode immediately after PRD content is confirmed (Inputs protocol), before entering Stage 1.

Why this order matters: If Diff Mode matches cache, we skip Stage 1 entirely (no need to re-extract requirements). If we do Stage 1 first and then discover cache, the extraction work is wasted.

Execution flow:

1. User provides PRD URL/path
2. Inputs protocol: confirm Feishu title (if URL)
3. Extract full PRD content ← Content ready
4. ↓
5. ✨ EXECUTE DIFF MODE NOW (Steps C1-C3)
   ├─ C1: Locate cache by doc_id or filename
   ├─ C2: Check fingerprint (server-time or text-based)
   └─ C3: Ask user "audit changes only or full audit?"
   
   If cache hit + no changes → Exit, output cached report
   If cache hit + changes → Enter Diff Mode (Steps D1-D3)
   If no cache found → Continue to Stage 1
   
6. ↓
7. [Stage 1 — Requirement Extraction] (only if no cache or Diff Mode decision)

Key decision: After C1-C3, make a binary choice:

• Path A: Diff Mode (C1-C3 → D1-D3) — for cached PRD with changes
• Path B: Full Phase 1 audit — for new PRD or cache miss
• Path C: Reuse cached report — for cached PRD with no changes, exit

Phase 1: Conflict Detection (PRD vs Code)

Execute these stages sequentially. Do not skip stages.

Note: Phase 1 is only entered if Diff Mode check (above) determines a full audit is needed.

Stage 1 — Requirement Extraction

Read the PRD document. Extract a structured requirement list:

For each requirement, extract:
- req_id: Sequential identifier (R1, R2, R3...)
- summary: One-line description
- keywords: 3-8 search terms for locating related code
- type: FEATURE_NEW | FEATURE_MODIFY | FEATURE_REMOVE | CONSTRAINT | NON_FUNCTIONAL

For keyword extraction guidance, read references/requirement-taxonomy.md if it exists.

After outputting the table, use AskUserQuestion:

• Question: "以上共 {n} 条需求，确认后进入 Stage 2，或告知需要调整的条目。"
• Options: ["确认，全部正确", "有条目需要调整（请在 Other 中说明）"] Wait for user's response before proceeding.

Stage 2 — Project Reconnaissance

Command Timeout Convention: All external commands (rg, find, grep) use timeout {T} where T adapts to project scale:

• Small project (<30 files): T=30s
• Medium project (30-200 files): T=60s
• Large project (200+ files): T=120s Estimate file count early via find <dir> -maxdepth 2 -type f | wc -l and set T accordingly.

Path Safety Check (execute first):

• Resolve <dir> to an absolute path
• Verify it is NOT a system root (/, /etc, /usr, C:\, C:\Windows, etc.)
• If validation fails → abort with: ❌ 项目目录路径异常：{path}。请提供项目根目录的绝对路径。

1. Read top-level structure: timeout {T} find <dir> -maxdepth 3 -type f | head -80
2. Read key metadata files (if they exist): README.md, package.json, pyproject.toml, go.mod, etc.
3. Read source folder tree: timeout {T} find <src> -maxdepth 4 -type f | head -120

Produce a ≤300-word Project Profile (language, framework, main dirs, DB, API layer).

Stage 2.5 — Documentation Health Check (Best-Effort)

⚠️ This stage is best-effort. Results inform but do not gate subsequent stages.

Scale-Adaptive Skip: Estimate project size: timeout {T} find <src_dir> -type f \( -name "*.go" -o -name "*.ts" -o -name "*.py" -o -name "*.java" \) | wc -l

• If < 30 files (small project): Full documentation check (fast, few files — easy to verify completely).
• If >= 30 files: Sampling check — randomly select 5 key documents for freshness + accuracy verification.
• All project sizes continue with Stage 2.5 → 2.8 → 2.9.

Existence check:

• timeout {T} find <project_dir> -maxdepth 2 -name "*.md" -not -path "*/node_modules/*" | head -20
• If no documentation found → flag ⚠️ DOC_MISSING

Freshness check:

• If last modified > 90 days ago → flag ⚠️ DOC_STALE: {filename} last updated {date}

Accuracy verification (best-effort): Spot-check a few key claims in docs against actual code (paths exist? imports match?). Record: ✅ VERIFIED / ❌ CONTRADICTED / ⚠️ UNVERIFIABLE

Output: Documentation Trust Score

📋 Documentation Health
- Trust Level: HIGH (>80% verified) / MEDIUM (50-80%) / LOW (<50%) / NONE (no docs)

Impact on subsequent stages:

• Trust HIGH → Stage 3 can use doc-suggested paths as primary search targets
• Trust MEDIUM/LOW/NONE → Stage 3 treats docs as low-confidence hints, relies on rg/find discovery

Stage 2.8 — Auto-Generate Code Map (when docs insufficient)

Trigger: Documentation Trust Level is MEDIUM, LOW, or NONE. Skip if HIGH.

Generate a structured code map by reading the actual codebase:

# Find entry points, routers, handlers
timeout {T} rg -l "func main\b|app\.listen|router\.|@Controller|func.*Handler" <project> -t code | head -30
# Find model/entity definitions
timeout {T} rg -l "type.*struct|class.*Model|@Entity|schema\.|CREATE TABLE" <project> -t code | head -30
# Find API route definitions
timeout {T} rg -n "GET\|POST\|PUT\|DELETE\|@Get\|@Post\|router\.\|HandleFunc" <project> -t code | head -50

Write to {project_dir}/.prd-pilot/code-map-{date}.md. Mark uncertain entries with (?). This code map becomes the primary reference for Stage 3 and Stage 4.

Stage 2.9 — Scan Budget Preview

Estimate scan cost and confirm with user:

timeout {T} find <src_dir> -type f \( -name "*.go" -o -name "*.ts" -o -name "*.py" -o -name "*.java" -o -name "*.js" \) | xargs wc -l 2>/dev/null | tail -1

Use AskUserQuestion:

• Question: "预计扫描 {N} 个文件、{LOC}k 行，共 {R} 条需求，继续执行 Stage 3？"
• Options: ["继续，使用默认上限", "调整上限（请在 Other 中填写数字）"]

Stage 3 — Targeted Code Search

For each requirement from Stage 1:

1. timeout {T} rg -l "<keyword>" <project_dir> --type-add 'code:*.{ts,tsx,js,jsx,py,go,rs,java,rb,vue,svelte}' -t code
2. If 0 matching files → mark as UNLOCATED
3. For located requirements, read relevant sections: timeout {T} rg -n -C 5 "<keyword>" <file>
4. Cap at 2000 lines of code context per requirement (adjust per references/infrastructure.md context management)

This stage is tool-driven (rg/grep/find). Do not rely on LLM memory of the codebase.

Stage 4 — Cross Analysis

For each requirement, classify into:

Verdict	Meaning	Action Required
CONFLICT	PRD demands X, code does Y	Must resolve before coding
WARNING	Possible mismatch, could be indirect implementation	Human review needed
PASS	Requirement satisfied or compatible	No action
GAP	No existing code found (new feature needed)	Expected for new features
UNKNOWN	Cannot determine	Human review needed

Evidence rules:

• Every CONFLICT and WARNING must include: prd_excerpt, code_file, code_lines, reasoning
• If you cannot cite specific code evidence → classify as UNKNOWN, never as CONFLICT
• Err on the side of WARNING over CONFLICT when uncertain

False positive prevention:

• Before marking CONFLICT, ask: "Could a developer reasonably handle this without code changes?"
• HTTP status codes can convey success/failure → front-end maps codes to text
• Missing explicit string literals ≠ "cannot display"
• Standard framework conventions count as implementation
• "Different approach, same outcome" → PASS with note, not CONFLICT

Classification Decision Tree (boundary examples):

Scenario	Verdict	Reasoning
PRD: "显示成功提示", code returns {code: 200} without message	PASS	Frontend maps status codes to display text
PRD: "限制每人每天3次", no rate limiting code found	CONFLICT	Core constraint with no implementation evidence
PRD: "支持 Excel 导出", code has CSV export only	WARNING	Similar but not identical — context-dependent
PRD: "使用 Redis 缓存", code uses in-memory cache	WARNING	Different approach, may be intentional
PRD: "删除用户时同步删除关联数据", code soft-deletes only	CONFLICT	Data integrity requirement not met

Stage 5 — Report Assembly

First-time write permission check: Before writing to {project_dir}/.prd-pilot/ for the first time in a session, use AskUserQuestion:

• Question: "需要在项目目录创建 .prd-pilot/ 文件夹存放审计报告，是否允许？"
• Options: ["允许", "不允许，输出到终端即可"] If user declines → print report to conversation only; do not create files.

Read references/audit-output-format.md if it exists; otherwise use standardized format:

---
report_type: prd_audit
date: {YYYY-MM-DD}
prd_source: {source}
project_name: {name}
commit_hash: {hash}
summary:
  conflict: {n}
  warning: {n}
  gap: {n}
  pass: {n}
  unknown: {n}
---

# PRD Audit Report — {YYYY-MM-DD}

## Executive Summary
- Total requirements: {n}
- Status distribution: CONFLICT {n} | WARNING {n} | GAP {n} | PASS {n} | UNKNOWN {n}
- Blockers: {brief description of CONFLICTs requiring resolution}

## Findings by Category

### CONFLICT Findings
#### [{req_id}] {summary}
- **PRD Excerpt**: "{text}"
- **Code Location**: `{file}:{lines}`
- **Reasoning**: {2-3 sentences explaining mismatch}
- **Resolution**: [suggest action]

### WARNING Findings
#### [{req_id}] {summary}
- **PRD Excerpt**: "{text}"
- **Code Location**: `{file}:{lines}`
- **Reasoning**: {2-3 sentences explaining ambiguity}
- **Recommendation**: [human review suggestion]

### GAP Findings
#### [{req_id}] {summary}
- **PRD Excerpt**: "{text}"
- **Search Result**: [no code found for keywords: ...]
- **Implication**: New feature required or indirect implementation

### PASS Findings
#### [{req_id}] {summary}
- **Status**: Requirement satisfied in codebase

### UNKNOWN Findings
#### [{req_id}] {summary}
- **Reason**: [insufficient evidence to determine status]
- **Recommendation**: [suggest manual inspection or code context]

## Integration Notes

**For spec-kit:** CONFLICTs and WARNINGs become spec review items.
**For Superpowers:** Use findings to inform `superpowers:writing-plans` workflow.
**For taskforce_plan:** Neko consumes this report to refine specification and identify implementation blockers.

Write to: {project_dir}/.prd-pilot/audit-{YYYY-MM-DD}.md If within taskforce, also copy to blackboard/active/{task_id}_prd_audit.md

If .prd-pilot/ is not in .gitignore, display (do NOT auto-modify): 💡 建议将 .prd-pilot/ 加入 .gitignore 以避免提交审计报告和缓存文件。

Tool Ecosystem & Recommended Workflow

prd-pilot works best as part of a multi-tool pipeline. Use this chart to choose companion tools:

Scenario	Primary Tool	Companion	Purpose
Audit existing PRD	prd-pilot	—	Detect conflicts, gaps, risks
From audit → spec	prd-pilot	spec-kit	Convert audit findings to spec
From audit → plan	prd-pilot	Superpowers:writing-plans	Generate implementation roadmap
From audit → code	prd-pilot	taskforce_plan	Neko consumes audit for spec refinement
Review PR against PRD	Superpowers (verification-before-completion)	—	Check if changes match audit scope
Incremental PRD changes	prd-pilot (Diff Mode)	—	Re-audit only changed sections

Recommended Workflow:

1. Run prd-pilot to audit PRD against code
   ↓
2. Review audit report (CONFLICT/WARNING/GAP/PASS)
   ↓
3. Choose path:
   a) Use spec-kit to convert findings → formal spec
   b) Use Superpowers:writing-plans to generate implementation roadmap
   c) Feed audit to taskforce_plan for automated planning
   ↓
4. Execute plan
   ↓
5. Use Superpowers `verification-before-completion` or spec-kit review to validate PR coverage

💡 spec-kit and Superpowers are recommended companion tools — not required. Install them independently when needed; prd-pilot works standalone without them.

Integration with Taskforce

When used as a pre-step before taskforce_act:

1. PRD Pilot writes audit report to blackboard/active/{task_id}_prd_audit.md
2. In subsequent taskforce_plan, Neko reads this file to inform Spec generation
3. CONFLICTs become explicit resolution items; GAPs become new implementation items
4. PRD Pilot does NOT generate specs or code — it only detects and reports

Limitations

• Cannot trace through highly dynamic dispatch (eval, reflection, complex DI containers)
• May miss implementations behind 3+ levels of indirection
• Non-functional requirements cannot be verified by static analysis
• Best suited for: API contracts, data models, feature flags, UI routes, config schemas
• Least suited for: cross-service interactions, runtime behavior, timing constraints

Roadmap

See README.md for planned features and timeline.