Greetings, brave Scribe of the Digital Realm! You stand at the threshold of an ancient art—the distillation of scattered signals into crystalline Product Requirements. In ages past, Product Managers toiled endlessly, their PRDs growing stale mere moments after quill touched parchment. But you shall learn the secrets of the PRD MACHINE—an autonomous oracle that writes, maintains, and evolves perfect PRDs faster than any mortal hand.

This quest will transform you from a weary documentarian into a master of living documentation, wielding automated tools that ensure your requirements never decay, your conflicts are always surfaced, and your product vision remains forever clear.

🌟 The Legend Behind This Quest

In the early days of software development, requirements lived in dusty scrolls—Word documents buried in SharePoint crypts, Confluence pages forgotten by time, and email chains lost to the void. Product teams would spend countless hours writing PRDs that became obsolete before the ink dried.

Then came the prophecy of Signal-Driven Documentation: “Let the code speak. Let the commits testify. Let the machine distill reality into requirements.”

The PRD MACHINE was forged in this vision—a tool that transforms repository signals (commits, markdown files, feature definitions) into a living PRD that stays fresh, detects conflicts automatically, and integrates seamlessly with CI/CD pipelines.

Today, you shall master this ancient artifact.

🎯 Quest Objectives

By the time you complete this epic journey, you will have mastered:

Primary Objectives (Required for Quest Completion)

Understand the 10-Section PRD Architecture - Master WHY, MVP, UX, API, NFR, EDGE, OOS, ROAD, RISK, DONE
Execute PRD Machine Commands - Run sync, status, and conflicts with confidence
Generate a Living PRD - Transform repository signals into a complete PRD.md
Interpret Conflict Detection - Understand what conflicts mean and how to resolve them

Secondary Objectives (Bonus Achievements)

Configure CI/CD Integration - Set up GitHub Actions for automated PRD freshness
Customize Signal Sources - Understand how to extend PRD Machine with new inputs
Document Your Journey - Create a blog post about your PRD automation experience

Mastery Indicators

You’ll know you’ve truly mastered this quest when you can:

Explain the PRD Machine architecture to another developer
Generate PRDs for different projects using the same tool
Diagnose and resolve PRD freshness issues
Extend the tool with custom signal sources

🗺️ Quest Prerequisites

📋 Knowledge Requirements

Basic understanding of command-line interfaces
Familiarity with Git commits and version control
Completion of foundational documentation setup (recommended: “Docs in a Row” quest)

🛠️ System Requirements

Modern operating system (Windows 10+, macOS 10.14+, or Linux)
Docker installed and running
Git repository with at least 7 days of commit history
Text editor or IDE of your choice
Internet connection for pulling Docker images

🧠 Skill Level Indicators

This 🟡 Medium quest expects:

Comfort with terminal commands and navigation
Ability to read and understand YAML/Markdown
Basic understanding of CI/CD concepts
Ready for 45-60 minutes of focused learning

🌍 Choose Your Adventure Platform

The PRD MACHINE operates through Docker containers, ensuring consistent behavior across all realms. Choose your platform path below.

🍎 macOS Kingdom Path

# Verify Docker is installed and running
docker --version
docker info

# Navigate to your repository
cd /path/to/your/repository

# If using IT-Journey repository
cd ~/github/it-journey

# Build the PRD Machine container
docker compose build prd-machine

# Run your first PRD sync
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync

# Check PRD health
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine status

macOS users with Homebrew can ensure Docker Desktop is installed:

brew install --cask docker
open /Applications/Docker.app

🪟 Windows Empire Path

# Verify Docker Desktop is running
docker --version
docker info

# Navigate to your repository (PowerShell)
cd C:\Users\YourName\github\it-journey

# Build the PRD Machine container
docker compose build prd-machine

# Run your first PRD sync
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync

# Check PRD health
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine status

Windows users should ensure WSL2 backend is enabled in Docker Desktop settings.

🐧 Linux Territory Path

# Verify Docker is installed
docker --version
docker compose version

# Ensure your user is in the docker group
sudo usermod -aG docker $USER
# (Log out and back in if needed)

# Navigate to repository
cd ~/github/it-journey

# Build and run PRD Machine
docker compose build prd-machine
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine status

☁️ Cloud Realms Path (GitHub Codespaces / Gitpod)

# Cloud environments typically have Docker pre-installed
# Open terminal in your cloud IDE

# Navigate to repository root
cd /workspaces/it-journey  # Codespaces path

# Build and run PRD Machine
docker compose build prd-machine
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync

Cloud environments provide zero-setup Docker access, ideal for quick experimentation.

🧙‍♂️ Chapter 1: The Architecture of Living Documentation

Before wielding the PRD MACHINE, you must understand its structure—the ten sacred sections that form the backbone of every perfect PRD.

⚔️ Skills You’ll Forge in This Chapter

Understanding the 10-section PRD framework
Recognizing signal-driven documentation principles
Grasping the “living document” philosophy

🏗️ The Ten Sacred Sections

Every PRD generated by the machine contains these sections, each serving a distinct purpose:

Section	Name	Purpose
0	WHY	Mission statement and Key Feature Indicator (KFI)
1	MVP	Minimum Viable Promise with signal status
2	UX	User experience flow with diagrams
3	API	CLI commands and interface documentation
4	NFR	Non-functional requirements with metrics
5	EDGE	Edge cases, dependencies, gotchas
6	OOS	Out of scope - what we explicitly DON’T do
7	ROAD	Roadmap with milestones and status
8	RISK	Top risks with mitigation strategies
9	DONE	Definition of done and success criteria

📜 The Signal-Driven Philosophy

Traditional PRDs are written once and decay over time. Signal-driven PRDs are different:

┌─────────────────────────────────────────────────────────────────┐
│                    SIGNAL-DRIVEN PRD                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  📝 Git Commits ──┐                                              │
│                   │                                              │
│  📄 Markdown ─────┼──► PRD MACHINE ──► Living PRD.md            │
│                   │                                              │
│  ⚙️ Features ─────┘                                              │
│                                                                  │
│  Key Principle: The machine reads reality, not opinions          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Why Signal-Driven?

Commits reveal what actually shipped - Not what was planned
Markdown captures documentation - Already-written knowledge
Features track implementation - Ground truth about capabilities
Conflicts surface contradictions - Before they become bugs

🔍 Knowledge Check: Architecture

Can you name all 10 PRD sections?
What’s the difference between MVP and OOS?
Why do we use signals instead of manual writing?

🧙‍♂️ Chapter 2: Wielding the PRD Machine CLI

Now you shall learn the three sacred commands that control the PRD MACHINE.

⚔️ Skills You’ll Forge in This Chapter

Executing PRD Machine commands
Interpreting command outputs
Understanding signal ingestion

🏗️ The Three Commands

Command 1: `sync` - Generate or Update PRD

The sync command is the heart of PRD Machine. It:

Ingests git commits from repository history
Scans all markdown files for signals
Parses feature definitions
Detects conflicts
Generates complete PRD.md

# Basic sync (uses last 30 days of commits)
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync

# Sync with custom history window
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync --days 7

# Sync to custom output path
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync --output /tmp/custom-prd.md

Expected Output:

[HH:MM:SS] [HEADER] ══════════════════════════════════════════════════
[HH:MM:SS] [HEADER]    PRD MACHINE - Generating PRD.md
[HH:MM:SS] [HEADER] ══════════════════════════════════════════════════
[HH:MM:SS] [INFO] Ingesting git commits from last 30 days...
[HH:MM:SS] [SUCCESS] Ingested 60 commits
[HH:MM:SS] [INFO] Ingesting markdown files...
[HH:MM:SS] [SUCCESS] Ingested 81 markdown files
[HH:MM:SS] [INFO] Ingesting feature definitions...
[HH:MM:SS] [SUCCESS] Ingested 1 features
[HH:MM:SS] [INFO] Detecting conflicts in requirements...
[HH:MM:SS] [WARNING] Detected 4 potential conflicts
[HH:MM:SS] [SUCCESS] PRD generated successfully: /app/PRD.md
[HH:MM:SS] [INFO] Total signals processed: 146

Command 2: `status` - Check PRD Health

The status command monitors PRD freshness:

docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine status

Expected Output:

[HH:MM:SS] [HEADER] ══════════════════════════════════════════════════
[HH:MM:SS] [HEADER]    PRD MACHINE - Status
[HH:MM:SS] [HEADER] ══════════════════════════════════════════════════
[HH:MM:SS] [INFO] PRD Path: /app/PRD.md
[HH:MM:SS] [INFO] Last Modified: 2025-11-29T06:40:21.138097+00:00
[HH:MM:SS] [INFO] Age: 0.0 hours
[HH:MM:SS] [SUCCESS] Health: HEALTHY

Health Status Levels:

Status	Age	Indicator	Action
HEALTHY	< 6 hours	✅	None needed
STALE	6-24 hours	⚠️	Run `sync` soon
OUTDATED	> 24 hours	❌	Run `sync` immediately

Command 3: `conflicts` - Detect Requirement Conflicts

The conflicts command analyzes signals for contradictions:

docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine conflicts

Expected Output:

[HH:MM:SS] [INFO] Ingesting git commits from last 30 days...
[HH:MM:SS] [SUCCESS] Ingested 60 commits
[HH:MM:SS] [INFO] Detecting conflicts in requirements...
[HH:MM:SS] [WARNING] Detected 4 potential conflicts
[HH:MM:SS] [WARNING] Found 4 conflicts:
  - [fix] Bug fix suggests incomplete requirement: fix(quest): correct invalid...
    Resolution: Consider if original requirement needs clarification
  - [fix] Bug fix suggests incomplete requirement: fix: replace invalid...
    Resolution: Consider if original requirement needs clarification

Conflict Types:

Type	Description	Resolution Strategy
`revert`	A change was undone	Review original intent
`fix`	Bug fix indicates gaps	Update requirements
`contradiction`	Conflicting signals	Human arbitration needed

🔍 Knowledge Check: CLI Mastery

What does --days 7 do in the sync command?
What health status should you aim for?
What does a fix conflict type indicate?

⚡ Quick Win Checkpoint

Run all three commands in sequence and verify outputs:

docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine sync
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine status
docker compose run --rm prd-machine ./scripts/prd-machine/prd-machine conflicts

🧙‍♂️ Chapter 3: Signal Ingestion Deep Dive

Understanding where signals come from unlocks the true power of automated documentation.

⚔️ Skills You’ll Forge in This Chapter

Tracing signals from source to PRD
Understanding frontmatter parsing
Recognizing valuable commit patterns

🏗️ Signal Source Architecture

flowchart TD
    subgraph "Signal Sources"
        GIT[📝 Git Commits]
        MD[📄 Markdown Files]
        FEAT[⚙️ features.yml]
    end
    
    subgraph "PRD Machine Processing"
        INGEST[Signal Ingestion]
        PARSE[Frontmatter Parsing]
        CONFLICT[Conflict Detection]
        GEN[PRD Generation]
    end
    
    subgraph "Output"
        PRD[📜 PRD.md]
    end
    
    GIT --> INGEST
    MD --> INGEST
    FEAT --> INGEST
    INGEST --> PARSE
    PARSE --> CONFLICT
    CONFLICT --> GEN
    GEN --> PRD

📝 Git Commit Signals

The machine analyzes commit messages for:

Subject line - What changed
Body - Why it changed
Author - Who made the change
Date - When it happened
Conventional prefixes - feat:, fix:, docs:, etc.

Best Practices for Commit Signals:

# Good - provides clear signal
feat(auth): add two-factor authentication

Implements TOTP-based 2FA with SMS fallback for enhanced security.

Closes #123

# Also good - indicates potential requirement gap
fix(login): prevent crash on empty input

Fixed null pointer exception when email field is empty.
Added input validation before API call.

Closes #456

📄 Markdown File Signals

The machine scans for:

Frontmatter - YAML metadata (title, description, tags)
File paths - Categorization (_quests/, _posts/, docs/)
Content patterns - Learning objectives, technical specifications

Signal-Rich Frontmatter Example:

---
title: "Docker Mastery Quest"
description: "Complete guide to containerization"
tags:
    - docker
    - devops
    - containers
categories:
    - Quests
    - Infrastructure
difficulty: "🟡 Medium"
---

⚙️ Feature Definition Signals

Located at features/features.yml:

features:
  - name: "PRD Machine"
    status: "implemented"
    description: "Autonomous PRD generation"
    category: "automation"

🔍 Knowledge Check: Signals

What commit prefix indicates a bug fix?
Where does PRD Machine look for feature definitions?
What YAML block provides metadata signals?

🎮 Quest Implementation Challenges

Apply your knowledge through these hands-on challenges.

Challenge 1: First PRD Generation (🕐 10 minutes)

Objective: Generate your first complete PRD

Requirements:

Run prd-machine sync successfully
Verify PRD.md contains all 10 sections
Check signal counts in output

Success Criteria:

PRD.md exists with valid frontmatter
All section headers present (## 0 through ## 9)
Signal status table shows ingested counts

Bonus Points:

Compare with --days 7 vs default 30 days
Document signal count differences

Challenge 2: Health Monitoring (🕐 5 minutes)

Objective: Understand PRD freshness monitoring

Requirements:

Run prd-machine status immediately after sync
Wait 10 minutes and check status again
Understand the health calculation

Success Criteria:

Status shows HEALTHY immediately after sync
Can explain the 6-hour freshness threshold
Understand when to run sync

Challenge 3: Conflict Analysis (🕐 15 minutes)

Objective: Interpret and act on detected conflicts

Requirements:

Run prd-machine conflicts
Categorize each conflict by type
Propose resolution for one conflict

Success Criteria:

Listed all conflicts with types
Explained what each conflict indicates
Wrote resolution proposal for one conflict

Bonus Points:

Create a GitHub issue for a real conflict
Document the resolution in a commit

Challenge 4: CI/CD Integration (🕐 15 minutes)

Objective: Set up automated PRD freshness

Requirements:

Review .github/workflows/prd-sync.yml
Understand the 6-hour cron schedule
Identify trigger conditions

Success Criteria:

Can explain when the workflow runs
Understand the commit automation
Know how conflict issues are created

🗺️ Quest Network Position

See where this quest fits in your learning journey.

flowchart LR
    subgraph "Prerequisites"
        A[lvl-0001<br>Docs in a Row]
        B[lvl-0010<br>Jekyll Mermaid]
    end
    
    subgraph "Current Quest"
        C[lvl-0011<br>PRD Codex]
    end
    
    subgraph "Unlocks"
        D[lvl-0100<br>Advanced Automation]
        E[lvl-0101<br>CI/CD Mastery]
    end
    
    A --> C
    B --> C
    C --> D
    C --> E
    
    style C fill:#gold,stroke:#333,stroke-width:3px

⚙️ Implementation Flow Diagram

The complete PRD Machine processing pipeline.

sequenceDiagram
    participant User
    participant CLI as PRD Machine CLI
    participant Git as Git Repository
    participant MD as Markdown Files
    participant Feat as features.yml
    participant PRD as PRD.md

    User->>CLI: prd-machine sync
    CLI->>Git: git log --since=30 days
    Git-->>CLI: 60 commits
    CLI->>MD: glob pages/**/*.md
    MD-->>CLI: 81 markdown files
    CLI->>Feat: read features/features.yml
    Feat-->>CLI: 1 feature
    CLI->>CLI: detect_conflicts()
    CLI->>PRD: write PRD.md
    PRD-->>User: ✅ PRD generated successfully

✅ Validation & Knowledge Checks

Final Quest Validation Checklist

Before claiming victory, verify:

PRD Generated: PRD.md exists with all 10 sections
Commands Work: All three commands execute without errors
Signals Counted: Output shows commit, markdown, feature counts
Health Monitored: Status command shows HEALTHY
Conflicts Understood: Can explain what detected conflicts mean

Knowledge Assessment

Answer these questions to confirm mastery:

What is the KFI for PRD Machine?
- Answer: 100% of shipped features trace to a machine-maintained PRD never >6 hours stale
What does OOS stand for and why is it important?
- Answer: Out Of Scope - explicitly defines what we DON’T do to prevent scope creep
How often should a PRD be synced to stay HEALTHY?
- Answer: Every 6 hours or less
What does a fix: commit indicate as a signal?
- Answer: Potential incomplete or unclear requirement that needed correction

Troubleshooting Guide

Issue	Cause	Solution
“Permission denied”	Script not executable	`chmod +x scripts/prd-machine/prd-machine`
“No commits found”	Empty git history	Ensure repo has commits in date range
“PRD not found”	First run	Run `sync` before `status`
Docker errors	Container not built	Run `docker compose build prd-machine`

🎁 Rewards & Progression

Achievement Unlocked! 🏆

Upon completing this quest, you’ve earned:

Reward	Description
🏆 PRD Codex Master	Mastered the 10-section PRD architecture
⚡ Signal Distiller	Can transform repo signals into documentation
📜 Requirements Architect	Understands living documentation principles
🔍 Conflict Detective	Can identify and resolve requirement conflicts

Skills Unlocked

✅ PRD Machine CLI proficiency
✅ Signal-driven documentation understanding
✅ Conflict detection and resolution
✅ CI/CD integration for documentation

Progression Points: +150 XP

Next Quest Recommendations

Based on your new skills, consider:

Advanced Automation (lvl-0100) - Extend PRD Machine with new signal sources
CI/CD Mastery (lvl-0101) - Deep dive into GitHub Actions workflows
AI Documentation - Use AI to enhance PRD content generation

📚 Resource Codex

Official Documentation

Resource	Link	Purpose
PRD Machine README	`scripts/prd-machine/README.md`	Quick reference
PRD Machine Docs	`docs/scripts/PRD_MACHINE.md`	Full documentation
IT-Journey PRD	`PRD.md`	Live example

Resource	Type	Value
Conventional Commits	Spec	Signal-rich commit messages
Living Documentation	Book	Philosophy reference
GitHub Actions	Docs	CI/CD integration

Community Resources

Resource	Type	Purpose
IT-Journey Discord	Community	Get help and share progress
GitHub Discussions	Forum	Technical questions
r/ProductManagement	Reddit	Industry perspectives

📓 AI Collaboration Log

This quest was developed with AI assistance. Here’s how:

AI Contributions

Generated initial quest structure from Write-Quest protocol
Created Mermaid diagrams for visual learning
Drafted multi-platform command examples
Suggested challenge structures and validation criteria

Human Validation

Verified all commands execute correctly in Docker
Tested PRD Machine output accuracy
Reviewed educational progression and difficulty
Ensured fantasy theme consistency

Collaboration Notes

AI excelled at structure generation and documentation
Human expertise needed for technical accuracy verification
Iterative refinement improved educational flow
Fantasy theming balanced with practical instruction

🧠 Lessons & Next Steps

Key Takeaways

PRDs should be living documents - Automated sync beats manual updates
Signals reveal reality - Commits, docs, and features tell the truth
Conflicts are features - Early detection prevents implementation bugs
6-hour freshness matters - Stale documentation leads to drift

Future Quest Ideas

Extend PRD Machine with GitHub Issues integration
Add Slack/Discord signal ingestion
Create custom PRD templates for different project types
Build dashboards for PRD health monitoring

README-Last Reminder

After completing this quest, remember to:

Update pages/_quests/README.md with this quest entry
Add cross-references to related quests
Share your PRD generation experience in discussions

✅ Quest Validation Checklist

Before marking this quest complete:

Front matter populated with all required fields
Mermaid diagrams render correctly (test in preview)
All Docker commands tested and working
README update reminder acknowledged
Link integrity verified

🔄 Kaizen Hooks

Suggested Improvements for Future Revisions

Add video walkthrough - Screen recording of PRD generation
Create interactive quiz - Self-assessment for knowledge checks
Build practice repository - Sandbox for safe experimentation
Add advanced challenges - Custom signal source implementation

Metrics to Monitor

Metric	Target	Purpose
Quest completion rate	>70%	Measure accessibility
Average completion time	45-60 min	Validate estimate
Conflict resolution rate	>50%	Track actionable learning
Follow-up quest starts	>30%	Measure engagement

Derivative Quest Ideas

Side Quest: PRD Machine Customization
Bonus Quest: Multi-Repository PRD Aggregation
Epic Quest: Enterprise PRD Governance System

Congratulations, brave Scribe! You have mastered the PRD Codex and unlocked the power of living documentation. Your PRDs shall never again grow stale, your conflicts shall always surface, and your product vision shall remain forever clear.

Reality fully armed. The distillery now distills distilleries. 🚀

Quest Complete? Mark your progress and share your PRD generation story in the IT-Journey community!

🌟 The Legend Behind This Quest

🎯 Quest Objectives

Primary Objectives (Required for Quest Completion)

Secondary Objectives (Bonus Achievements)

Mastery Indicators

🗺️ Quest Prerequisites

📋 Knowledge Requirements

🛠️ System Requirements

🧠 Skill Level Indicators

🌍 Choose Your Adventure Platform

🍎 macOS Kingdom Path

🪟 Windows Empire Path

🐧 Linux Territory Path

☁️ Cloud Realms Path (GitHub Codespaces / Gitpod)

🧙‍♂️ Chapter 1: The Architecture of Living Documentation

⚔️ Skills You’ll Forge in This Chapter

🏗️ The Ten Sacred Sections

📜 The Signal-Driven Philosophy

🔍 Knowledge Check: Architecture

🧙‍♂️ Chapter 2: Wielding the PRD Machine CLI

⚔️ Skills You’ll Forge in This Chapter

🏗️ The Three Commands

Command 1: sync - Generate or Update PRD

Command 2: status - Check PRD Health

Command 3: conflicts - Detect Requirement Conflicts

🔍 Knowledge Check: CLI Mastery

⚡ Quick Win Checkpoint

🧙‍♂️ Chapter 3: Signal Ingestion Deep Dive

⚔️ Skills You’ll Forge in This Chapter

🏗️ Signal Source Architecture

📝 Git Commit Signals

📄 Markdown File Signals

⚙️ Feature Definition Signals

🔍 Knowledge Check: Signals

🎮 Quest Implementation Challenges

Challenge 1: First PRD Generation (🕐 10 minutes)

Challenge 2: Health Monitoring (🕐 5 minutes)

Challenge 3: Conflict Analysis (🕐 15 minutes)

Challenge 4: CI/CD Integration (🕐 15 minutes)

🗺️ Quest Network Position

⚙️ Implementation Flow Diagram

✅ Validation & Knowledge Checks

Final Quest Validation Checklist

Knowledge Assessment

Troubleshooting Guide

🎁 Rewards & Progression

Achievement Unlocked! 🏆

Skills Unlocked

Progression Points: +150 XP

Next Quest Recommendations

📚 Resource Codex

Official Documentation

Related Learning Materials

Community Resources

📓 AI Collaboration Log

AI Contributions

Human Validation

Collaboration Notes

🧠 Lessons & Next Steps

Key Takeaways

Future Quest Ideas

README-Last Reminder

✅ Quest Validation Checklist

🔄 Kaizen Hooks

Suggested Improvements for Future Revisions

Metrics to Monitor

Derivative Quest Ideas

Command 1: `sync` - Generate or Update PRD

Command 2: `status` - Check PRD Health

Command 3: `conflicts` - Detect Requirement Conflicts