PRD Creator

Overview

Create LLM-native Product Requirements Documents that serve as machine-interpretable, safety-focused specifications for AI agent development workflows. This skill implements a hybrid Markdown+YAML format optimized for token efficiency, human readability, and strict structural compliance.

Key Principle: The PRD is not documentation—it is a control surface that prevents AI agents from going rogue. Structured requirements protect non-technical users from context poisoning, hallucination, and constraint violations.

---

When to Use This Skill

Use this skill when the user requests:

• "Help me write a PRD for [feature]"
• "Create a requirements document for [product]"
• "Review this PRD for LLM compatibility"
• "Convert this doc to LLM-native format"
• "Validate my PRD for compliance"
• "Make this PRD safe for AI agents"

Context indicators: User mentions PRD, product requirements, specification, feature definition, or expresses concerns about AI agent behavior, hallucination, or code safety.

---

Core Workflow

Workflow Decision Tree

┌─────────────────────────────────┐
│ User wants PRD-related help     │
└────────────┬────────────────────┘
             │
    ┌────────┴────────┐
    │                 │
    ▼                 ▼
┌─────────┐      ┌─────────────┐
│ New PRD │      │ Existing PRD│
└────┬────┘      └──────┬──────┘
     │                  │
     ▼                  ▼
Create from        ┌─────────┐
template           │ Convert │
(Step 1)           │   OR    │
                   │ Validate│
                   └────┬────┘
                        │
                   ┌────┴─────┐
                   ▼          ▼
              Convert     Validate
              (Step 2)    (Step 3)
                   │          │
                   └────┬─────┘
                        ▼
                   Review &
                   Iterate
                   (Step 4)

---

Step 1: Creating a New PRD

When to Use

User needs to create a PRD from scratch for a new feature or product.

Process

1. Understand the Feature

   • Ask clarifying questions about the feature/product
   • Identify user personas and their goals
   • Determine technical constraints (languages, frameworks, security requirements)
   • Clarify what is explicitly OUT of scope

2. Initialize the PRD

Run the initialization script:

scripts/init_prd.py <output-path>

Example:

scripts/init_prd.py ./prds/user-authentication.md

The script will prompt for:

• Product/Feature name
• Owner name
• Version number (default: 1.0.0)

3. Fill in Core Sections

Load assets/prd-template.md for reference structure. Use the following order (forward-chaining principle):

Section Order:

1. YAML frontmatter (metadata)
2. Overview & Goals (the "why")
3. Technical Constraints (immutable rules)
4. User Personas (the actors)
5. Functional Requirements (the "what")
6. Non-Functional Requirements (quality attributes)
7. Out of Scope (boundaries)
8. Success Metrics (validation)

Critical Safety Elements:

In YAML frontmatter:

llm_directives:
  temperature: 0.2  # Low temperature reduces hallucination
  persona: >
    You MUST NOT deviate from technical constraints or functional
    requirements without explicit approval.

In Technical Constraints:

## 2. Technical Constraints & Environment

**CRITICAL**: These constraints are immutable.

* **Forbidden Libraries/Patterns**: pickle, eval(), exec()

In Out of Scope:

## 6. Out of Scope (Non-Goals)

**CRITICAL**: Explicitly define what will NOT be built to prevent
scope creep and agent hallucination.

* [Feature X]
* [Feature Y]

4. Assign Unique IDs

Every requirement MUST have a machine-readable ID:

• User Stories: LAW-31, LAW-32, LAW-33 (3-digit format)
• Acceptance Criteria: AC-001-A, AC-001-B (matches parent US)
• NFRs: NFR-Perf-001, NFR-Sec-001 (category prefix)
• Personas: Persona-Admin, Persona-User (PascalCase)

Example:

### **LAW-31**: User Registration

* **As a**: Persona-NewUser
* **I want to**: Create an account
* **So that**: I can access platform features

**Acceptance Criteria**:

* **AC-001-A**: System MUST validate email format
* **AC-001-B**: System MUST require password minimum 12 characters
* **AC-001-C**: System MUST hash passwords using bcrypt cost factor 12

5. Write Atomic, Testable Criteria

Each acceptance criterion = one test case.

Bad (too vague):

* **AC-001-A**: The login should work and be secure

Good (testable, specific):

* **AC-001-A**: System MUST authenticate user with valid email and password
* **AC-001-B**: System MUST return 401 Unauthorized for invalid credentials
* **AC-001-C**: System MUST use constant-time comparison to prevent timing attacks

6. Validate

Run validation before considering the PRD complete:

scripts/validate_prd.py <path-to-prd.md>

Address all errors. Review warnings.

---

Step 2: Converting an Existing PRD

When to Use

User has an existing PRD (any format) that needs to be converted to LLM-native format.

Process

1. Analyze the Existing PRD

Run the conversion assistant:

scripts/convert_prd.py <path-to-existing-prd.md>

The tool provides:

• Structure analysis (what sections exist)
• Pattern detection (user stories, acceptance criteria)
• ID format check
• Actionable recommendations

2. Load Context for LLM Conversion

Use an LLM agent to perform the conversion:

Prompt Template:

Load the following files into context:
1. [Path to existing PRD]
2. assets/prd-template.md
3. references/validation-rules.md

Task: Convert the existing PRD to LLM-native format following the
template structure. Ensure:
- YAML frontmatter with llm_directives
- Forward-chaining section order (constraints before requirements)
- Unique IDs for all user stories (US-XXX)
- Unique IDs for all acceptance criteria (AC-XXX-Y)
- Technical Constraints section with security requirements
- Out of Scope section with explicitly excluded features

Validate output against validation-rules.md before returning.

3. Review LLM Output

Manually review the converted PRD for:

• ✅ All original requirements preserved
• ✅ IDs assigned correctly
• ✅ Technical constraints captured
• ✅ Out of Scope section populated
• ✅ Acceptance criteria are atomic and testable

4. Validate

scripts/validate_prd.py <converted-prd.md>

Address all errors before use.

---

Step 3: Validating an Existing PRD

When to Use

User has a PRD and wants to verify it meets LLM-native compliance standards.

Process

1. Run Validation Script

scripts/validate_prd.py <path-to-prd.md>

2. Review Output

The validator checks:

Errors (MUST fix):

• ❌ Missing or invalid YAML frontmatter
• ❌ Missing required sections
• ❌ Sections out of order (violates forward-chaining)
• ❌ Duplicate user story IDs
• ❌ Duplicate acceptance criteria IDs
• ❌ Invalid ID formats

Warnings (SHOULD review):

• ⚠️ User story ID not in 3-digit format (US-1 instead of LAW-31)
• ⚠️ AC ID doesn't match parent US (AC-042-A under LAW-31)
• ⚠️ Reference to non-existent ID
• ⚠️ Status not in recommended enum

3. Fix Issues

Address errors in order of priority:

1. YAML frontmatter issues (breaks machine parsing)

2. Missing required sections (incomplete specification)

3. Section ordering (affects LLM reasoning)

4. ID format and duplication (breaks traceability)

5. Re-validate

Run validation again until all errors are resolved:

scripts/validate_prd.py <path-to-prd.md> && echo "✅ PRD is compliant"

---

Step 4: Reviewing and Iterating

When to Use

After creating, converting, or validating a PRD, review for safety and completeness.

Safety Review Checklist

Reference references/safety-principles.md for detailed guidance.

YAML Frontmatter:

• status: approved (only approved PRDs for autonomous agents)
• llm_directives.temperature: 0.2 or lower (reduces hallucination)
• llm_directives.persona includes "MUST NOT deviate without approval"

Technical Constraints (Section 2):

• Section exists and appears BEFORE Functional Requirements
• Includes **CRITICAL** keyword
• Lists programming languages with versions
• Specifies frameworks and style guides
• Defines security requirements explicitly
• Includes "Forbidden Libraries/Patterns" (negative constraints)

Functional Requirements (Section 4):

• All user stories have unique US-XXX IDs (3 digits)
• All acceptance criteria have unique AC-XXX-Y IDs
• Each AC is atomic (one test case per criterion)
• Each AC uses MUST/SHOULD/MAY keywords (RFC 2119)

Out of Scope (Section 6):

• Section exists and is populated (not empty)
• Lists explicitly excluded features
• Includes **CRITICAL** keyword
• Mentions "prevent hallucination" in section header

Validation:

• validate_prd.py passes with zero errors
• All warnings reviewed and addressed if necessary

Quality Checklist

Granularity:

• Each user story represents ONE capability
• Each acceptance criterion is testable by ONE test case
• No compound requirements ("X and Y" or "X or Y")

Traceability:

• All IDs are unique
• AC numbering matches parent US (AC-001-X under LAW-31)
• Cross-references point to valid IDs

Completeness:

• All personas referenced in user stories are defined in Section 3
• All technical constraints are specific (not "use secure hashing" but "use bcrypt cost factor 12")
• All NFRs include measurable thresholds ("< 250ms" not "fast")

---

Advanced Usage

Integration with Traycer Enforcement Framework

For users working with custom agentic coding frameworks (like traycer-enforcement-framework):

1. Store PRD in Project Root

/project-root/
  ├── PRD.md          # LLM-native PRD
  ├── src/
  └── tests/

2. Configure Agent Context

Ensure agents load the PRD at the beginning of each session:

# Agent initialization
context = load_prd("./PRD.md")
agent.set_constraints(context.technical_constraints)
agent.set_personas(context.user_personas)
agent.set_requirements(context.functional_requirements)

3. Enforce Validation Gates

Add validation as a pre-commit hook:

#!/bin/bash
# .git/hooks/pre-commit

scripts/validate_prd.py PRD.md || {
  echo "❌ PRD validation failed. Fix errors before committing."
  exit 1
}

4. Use for RAG Context

When agents need implementation guidance:

# Query: "How to implement US-042?"
# RAG retrieves:
#   - US-042 chunk
#   - All AC-042-X chunks
#   - Referenced Technical Constraints
#   - Related Persona definitions

# Agent receives complete, coherent context

LLM Directives for Different Scenarios

Customize the llm_directives block based on use case:

Strict Production Code:

llm_directives:
  model: "gpt-4-turbo"
  temperature: 0.1  # Very low for deterministic output
  persona: >
    You are a senior engineer generating production code. You MUST NOT
    deviate from technical constraints. All code MUST be tested. Reject
    any request to implement Out of Scope features.

Exploratory Prototyping:

llm_directives:
  model: "gpt-4-turbo"
  temperature: 0.5  # Higher for creative solutions
  persona: >
    You are building a prototype. Follow technical constraints but
    propose alternative approaches when beneficial. Flag any Out of
    Scope features for discussion.

Test Generation:

llm_directives:
  model: "gpt-4-turbo"
  temperature: 0.2
  persona: >
    You are a QA engineer generating comprehensive test cases. For each
    acceptance criterion (AC-XXX-Y), generate positive, negative, and
    edge case tests. Ensure 100% coverage of all ACs.

---

Reference Files

For detailed information, load these files into context as needed:

references/prd-framework.md

Comprehensive framework documentation including:

• Format analysis (Markdown vs JSON)
• Forward-chaining principle explanation
• Section hierarchy rationale
• RAG integration patterns
• Production workflow examples

Load when: Need deep understanding of why the framework works this way, or designing custom workflows.

references/safety-principles.md

Detailed explanation of how LLM-native PRDs prevent agent misbehavior:

• Context poisoning prevention
• Hallucination mitigation
• Mesa-optimization safeguards
• Constraint violation protection

Load when: User expresses concerns about AI safety, agent control, or non-coder protection.

references/validation-rules.md

Complete validation rule reference:

• YAML frontmatter requirements
• Section ordering rules
• ID format specifications
• Acceptance criteria best practices

Load when: Debugging validation errors or authoring custom validation logic.

---

Assets

assets/prd-template.md

Blank template ready to copy and fill in. Use as starting point for new PRDs or reference for structure.

assets/prd-schema.json

JSON Schema for teams requiring pure JSON format or programmatic validation. Can be used with JSON Schema validators in CI/CD pipelines.

assets/example-prd.md

Complete, realistic example PRD for a user authentication system. Demonstrates:

• Proper ID formatting
• Atomic acceptance criteria
• Technical constraints with security requirements
• Out of Scope section
• Complete cross-reference index

Load when: User needs concrete example to understand format or best practices.

---

Common Patterns

Pattern 1: "AI as Junior PM"

Scenario: PM needs first draft of PRD quickly.

Workflow:

1. PM provides context (user research, business goals)
2. PM provides template: assets/prd-template.md
3. LLM generates 70-80% complete draft
4. PM refines and validates
5. Validate with scripts/validate_prd.py

Pattern 2: Incremental Feature Addition

Scenario: Adding new user stories to existing PRD.

Workflow:

1. Identify next available US-XXX ID
2. Write user story following format
3. Add atomic acceptance criteria (AC-XXX-Y)
4. Update Appendix A cross-reference index
5. Validate to ensure no duplicate IDs

Pattern 3: PRD Review Before Agent Use

Scenario: User finished draft, wants to ensure it's safe for agents.

Workflow:

1. Run scripts/validate_prd.py <prd.md>
2. Fix all errors
3. Load references/safety-principles.md
4. Review against Safety Review Checklist (Step 4)
5. Update status: approved in YAML frontmatter
6. Commit to version control

Pattern 4: Converting Legacy Documentation

Scenario: User has old requirements doc (Word, Google Docs, etc.).

Workflow:

1. Export to plain text or markdown
2. Run scripts/convert_prd.py <old-doc.md>
3. Review recommendations
4. Use LLM agent with template to convert
5. Manual review for accuracy
6. Validate with scripts/validate_prd.py
7. Iterate until compliant

---

Troubleshooting

Error: "Missing required metadata field: X"

Cause: YAML frontmatter missing required field.

Fix: Add to frontmatter:

version: 1.0.0
owner: your-name
status: draft
last_updated: 2025-01-15

Error: "Section order violation: 'Functional Requirements' should come after 'Technical Constraints'"

Cause: Sections out of forward-chaining order.

Fix: Reorder sections to match Step 1 section order. Technical Constraints MUST come before Functional Requirements.

Warning: "AC-042-A appears under LAW-31 but ID suggests it belongs to US-042"

Cause: Acceptance criterion under wrong user story.

Fix: Move AC-042-X criteria under their matching US-042 parent, or renumber if intentional.

Error: "Duplicate user story ID: LAW-35"

Cause: Same US-XXX ID used twice in document.

Fix: Find duplicate IDs and renumber one of them. Update all references.

Agent Hallucinating Features

Cause: Out of Scope section missing or too vague.

Fix: Add explicit Out of Scope section with **CRITICAL** keyword. List exact features that should NOT be built.

Agent Violating Technical Constraints

Cause: Constraints not explicit enough or placed after requirements.

Fix:

1. Move Technical Constraints to Section 2 (before requirements)
2. Add **CRITICAL** and **MUST** keywords
3. List forbidden patterns explicitly
4. Lower temperature in llm_directives to 0.1

---

Best Practices

1. Validate Early and Often: Run validate_prd.py after every major edit
2. Use Low Temperature: Set temperature: 0.2 or lower for production code generation
3. Be Explicit: "Use bcrypt cost factor 12" not "use secure hashing"
4. Define Negatives: Out of Scope section prevents hallucination
5. Atomic Criteria: One AC = one test case, always
6. Version Control: Commit PRD changes with descriptive messages
7. Status Discipline: Only set status: approved after thorough review
8. ID Consistency: Use 3-digit format (LAW-31) not variable digits (US-1)

---

Quick Reference

Create new PRD:

scripts/init_prd.py ./prds/my-feature.md
# Edit the file
scripts/validate_prd.py ./prds/my-feature.md

Convert existing PRD:

scripts/convert_prd.py ./old-prd.md
# Review recommendations
# Use LLM to convert with template
scripts/validate_prd.py ./new-prd.md

Validate PRD:

scripts/validate_prd.py ./PRD.md

Key ID Formats:

• User Stories: LAW-31, US-042, US-150
• Acceptance Criteria: AC-001-A, AC-042-B
• NFRs: NFR-Perf-001, NFR-Sec-002
• Personas: Persona-Admin, Persona-User

Safety Keywords:

• **CRITICAL** in Technical Constraints and Out of Scope headers
• MUST / SHOULD / MAY in acceptance criteria (RFC 2119)
• temperature: 0.2 or lower in llm_directives