doc-prd-audit（文档 PRD 审核）

doc-prd-audit

Purpose

Run a unified PRD audit workflow that combines structural validation and content quality checks into a single pass, producing one combined report optimized for doc-prd-fixer input.

2-Skill Model: This skill replaces the separate doc-prd-validator and doc-prd-reviewer skills (now deprecated). All validation and review logic is consolidated here.

Deprecated Skills:

Layer: 2 (PRD Quality Gate Wrapper)

Upstream: PRD file(s)

Downstream:

• Combined Audit Report: PRD-NN.A_audit_report_vNNN.md
• Optional Fix Cycle trigger for doc-prd-fixer

Why This Skill Exists

The 2-skill model (doc-prd-audit + doc-prd-fixer) simplifies the PRD quality workflow.

Fresh Audit Policy (MANDATORY)

ALWAYS run the audit from scratch. Do NOT:

• Reference previous audit reports for scoring decisions
• Skip validation steps based on drift cache history
• Assume compliance from prior fix history
• Use cached results from previous runs

ALWAYS:

• Run all validation scripts fresh every time
• Re-check all structure/schema compliance
• Re-compute EARS-Ready and SYS-Ready scores independently
• Generate a new audit report with incremented version

When to Use

Use doc-prd-audit when:

• You want one command for PRD quality checks
• You need a combined report for doc-prd-fixer
• You are running CI/manual QA before EARS generation

Do NOT use when:

• PRD does not exist (use doc-prd / doc-prd-autopilot generation first)
• You only need one specific check domain (use validator or reviewer directly)

Execution Contract

Input

• PRD path (docs/02_PRD/PRD-NN_*/...)
• Optional: threshold (default review threshold: 90)

Sequence (Mandatory)

1) Run doc-prd-validator (internal)
2) Run doc-prd-reviewer (internal)
3) Normalize and merge findings
4) Write PRD-NN.A_audit_report_vNNN.md
5) Create/Update .drift_cache.json (MANDATORY)
6) If auto-fixable findings exist, hand off to doc-prd-fixer

Drift Cache Creation (MANDATORY)

After every audit, the skill MUST create or update .drift_cache.json in the PRD folder.

Location: docs/02_PRD/{PRD_folder}/.drift_cache.json

Schema (v1.2):

{
  "schema_version": "1.2",
  "document_id": "PRD-NN",
  "document_version": "X.Y",
  "upstream_mode": "brd",
  "upstream_ref_path": "../../01_BRD/BRD-NN_{slug}/",
  "drift_detection_skipped": false,
  "last_reviewed": "YYYY-MM-DDTHH:MM:SS",
  "last_fixed": "YYYY-MM-DDTHH:MM:SS",
  "reviewer_version": "2.2",
  "fixer_version": null,
  "autopilot_version": null,
  "upstream_documents": {
    "../../01_BRD/BRD-NN_{slug}/BRD-NN.0_index.md": {
      "hash": "sha256:<64-hex-chars>",
      "last_modified": "YYYY-MM-DDTHH:MM:SS",
      "file_size": 12345,
      "version": "X.Y"
    }
  },
  "review_history": [
    {
      "date": "YYYY-MM-DDTHH:MM:SS",
      "score": 100,
      "drift_detected": false,
      "report_version": "vNNN",
      "review_type": "audit",
      "status": "PASS"
    }
  ],
  "fix_history": []
}

Required Actions:

1. Create if .drift_cache.json does not exist
2. Update last_reviewed timestamp
3. Append to review_history array with current audit results
4. Compute SHA-256 hashes for all tracked upstream BRD documents
5. Set drift_detected: true if any upstream hash changed since last review

Hash Computation:

sha256sum <upstream_file> | cut -d' ' -f1

Error Codes:

Combined Status Rules

• PASS: Validator PASS AND Reviewer score >= threshold AND no blocking issues
• FAIL: Validator FAIL OR Reviewer score < threshold OR blocking/manual-required issues present

Diagram Contract Gate (BLOCKING for PRD)

Audit MUST fail when any blocking diagram code is present:

• PRD-E023 missing @diagram: c4-l2
• PRD-E024 missing @diagram: dfd-l1
• PRD-E025 missing @diagram: sequence-*
• PRD-E026 sequence diagram missing alt/else exception path

Also include warning diagnostics when present:

• PRD-W011 diagram intent metadata incomplete

Element Code Contract Gate (BLOCKING for PRD)

Audit MUST fail when element type codes violate naming standards:

• PRD-E020 Element type code not valid for PRD (must be in VALID_PRD_CODES set)
• PRD-E022 Section-element type code mismatch (e.g., Section 5 metrics must use type 08)

Valid PRD Type Codes: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 22, 24, 32

Section-Element Mapping (Enforced):

Validation Command:

bash ai_dev_ssd_flow/02_PRD/scripts/prd_standardized_element_codes_hook.sh <path>

Validation Checks (from deprecated doc-prd-validator)

1. Metadata Validation

Required custom_fields:
  document_type: ["prd", "template"]
  artifact_type: "PRD"
  layer: 2
  architecture_approaches: [array format]
  priority: ["primary", "shared", "fallback"]
  development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - prd (or prd-template)
  - layer-2-artifact

Forbidden tag patterns:
  - "^product-requirements$"
  - "^product-prd$"
  - "^feature-prd$"

2. Structure Validation (MVP Template - 17 Sections)

Required Sections (MVP Template):

3. Document Control Required Fields

4. Dual Scoring Requirements

Both scores must be present and meet thresholds for downstream artifact generation.

5. File Naming Convention

Pattern: PRD-NN_{descriptive_slug}.md

• NN: 2+ digit number (01, 02,... 99, 100)
• descriptive_slug: lowercase with underscores

6. Traceability Validation

Layer 2 Cumulative Tags (Required):

@brd: BRD.NN.xxxx

Unified Element ID Format: PRD.NN.xxxx

7. Structure Compliance (Nested Folder Rule)

ALL PRDs MUST use nested folders regardless of size.

Review Checks (from deprecated doc-prd-reviewer)

1. Link Integrity

Validates all internal document links resolve correctly.

Error Codes:

2. Threshold Consistency

Verifies performance metrics match across all sections.

Error Codes:

3. Diagram Contract Compliance

Error Codes:

4. BRD Alignment

Validates PRD requirements accurately reflect BRD source.

Error Codes:

5. Placeholder Detection

Error Codes:

6. Traceability Tags

Error Codes:

7. Section Completeness

Minimum Word Counts (configurable):

Error Codes:

8. Customer Content Review

Error Codes:

9. Naming Compliance

Error Codes:

10. Upstream Drift Detection

Cache File: docs/02_PRD/{PRD_folder}/.drift_cache.json

Error Codes:

Validator Error Codes

Combined Report Format (for doc-prd-fixer)

Output file: PRD-NN.A_audit_report_vNNN.md

Required sections:

1. ## Summary

- PRD ID, timestamp (EST), overall status - Validator status, reviewer score

1. ## Score Calculation (Deduction-Based)

- Formula: 100 - total_deductions - Deductions grouped by: contamination (max 50), FR completeness (max 30), structure/quality (max 20) - Threshold comparison (>=90 pass gate)

1. ## Validator Findings

- List by severity/code

1. ## Reviewer Findings

- List by severity/code

1. ## Diagram Contract Findings

- Required PRD tags status (c4-l2, dfd-l1, sequence-*) - Exception-flow evidence status (alt/else) - Intent header completeness status

1. ## Fix Queue for doc-prd-fixer

- auto_fixable - manual_required - blocked

1. ## Recommended Next Step

- run doc-prd-fixer - or manual update required

Fix Queue Normalization

Each finding MUST include:

• source: validator | reviewer
• code: issue code
• severity: error|warning|info
• file: relative path
• section: heading/anchor if known
• action_hint: short imperative guidance
• confidence: high|medium|manual-required

Hand-off Contract to doc-prd-fixer

doc-prd-fixer MUST accept combined audit report as equivalent upstream input:

• PRD-NN.A_audit_report_vNNN.md (preferred)
• PRD-NN.R_review_report_vNNN.md (legacy compatibility)

If both exist, fixer should prefer latest timestamp.

Validation Commands

# Canonical wrapper (core only; pre-commit/CI parity)
bash ai_dev_ssd_flow/02_PRD/scripts/prd_core_wrapper_hook.sh ai_dev_ssd_flow/02_PRD

# Strict PRD ID checks (same quality class as BRD ID checks)
bash ai_dev_ssd_flow/02_PRD/scripts/prd_standardized_element_codes_hook.sh ai_dev_ssd_flow/02_PRD
bash ai_dev_ssd_flow/02_PRD/scripts/prd_legacy_pattern_hook.sh ai_dev_ssd_flow/02_PRD

# Canonical wrapper (core + advisory)
bash ai_dev_ssd_flow/02_PRD/scripts/validate_prd_wrapper.sh docs/02_PRD

# Validate single PRD document (must be in nested folder)
python ai_dev_ssd_flow/02_PRD/scripts/validate_prd.py docs/02_PRD/PRD-01_example/PRD-01_example.md

# Validate all PRD documents in directory
python ai_dev_ssd_flow/02_PRD/scripts/validate_prd.py docs/02_PRD/

# Validate with verbose output
python ai_dev_ssd_flow/02_PRD/scripts/validate_prd.py docs/02_PRD/ --verbose

# Validate with auto-fix (includes structure fixes)
python ai_dev_ssd_flow/02_PRD/scripts/validate_prd.py docs/02_PRD/ --auto-fix

# Cross-document validation
python ai_dev_ssd_flow/scripts/validate_cross_document.py --document docs/02_PRD/PRD-01_slug/PRD-01_slug.md --auto-fix

# Layer-wide validation
python ai_dev_ssd_flow/scripts/validate_cross_document.py --layer PRD --auto-fix

Example Invocation

/doc-prd-audit docs/02_PRD/PRD-01_f1_iam/PRD-01_f1_iam.md

Expected outcome:

1. validator runs (internal)
2. reviewer runs (internal)
3. combined audit report generated
4. fixer can execute directly from combined report

Related Skills

Version History

Implementation Plan Consistency (IPLAN-004)

• Treat plan-derived outputs as valid source mode and verify intent preservation from implementation plan scope/objectives.
• Validate upstream autopilot precedence assumption: --iplan > --ref > --prompt.
• Flag objective/scope conflicts between plan context and artifact output as blocking issues requiring clarification.
• Do not introduce legacy fallback paths such as docs-v2.0/00_REF.