Blueprint Derive Plans

/blueprint:derive-plans

Retroactively generate Blueprint documentation (PRDs, ADRs, PRPs) from an existing established project by analyzing git history, codebase structure, and existing documentation.

Use case: Onboarding established projects into the Blueprint Development system when PRD/ADR/PRP documents don't exist but the project has implementation history.

When to Use This Skill

Context

• Git repository: !git rev-parse --git-dir
• Blueprint initialized: !find docs/blueprint -maxdepth 1 -name 'manifest.json' -type f
• Total commits: !git rev-list --count HEAD
• First commit: !git log --reverse --format=%ai --max-count=1
• Latest commit: !git log --max-count=1 --format=%ai
• Project type: !find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'pom.xml' \) -type f -print -quit
• Documentation files: !find . -maxdepth 2 \( -name "README.md" -o -name "ARCHITECTURE.md" -o -name "DESIGN.md" \)

Parameters

Parse these from $ARGUMENTS:

• --quick: Fast scan (last 50 commits only)
• --since DATE: Analyze commits from specific date (e.g., --since 2024-01-01)

Default behavior without flags: Standard analysis (last 200 commits with scope estimation).

For detailed templates, manifest format, and report examples, see REFERENCE.md.

Execution

Execute this retroactive documentation generation workflow:

Step 1: Verify prerequisites

Check context values above:

1. If git repository = "NO" → Error: "This directory is not a git repository. Run from project root." 2. If total commits = "0" → Error: "Repository has no commit history" 3. If Blueprint initialized = "NO" → Ask user: "Blueprint not initialized. Initialize now (Recommended) or minimal import only?"

• If "Initialize now" → Use Task tool to invoke /blueprint:init, then continue with this step 1
• If "Minimal import only" → Create minimal directory structure: mkdir -p docs/prds docs/adrs docs/prps

Step 2: Determine analysis scope

Parse $ARGUMENTS for --quick or --since:

1. If --quick flag present → scope = last 50 commits 2. If --since DATE present → scope = commits from DATE to now 3. Otherwise → Present options to user:

• Quick scan (last 50 commits)
• Standard analysis (last 200 commits)
• Full history analysis (all commits)
• Custom date range

Use selected scope for all subsequent git analysis.

Step 3: Analyze git history quality

For commits in scope, calculate:

1. Count total commits: git log --oneline {scope} | wc -l 2. Count conventional commits: git log --format="%s" {scope} | grep -cE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\(?.*\)?:" || echo 0 3. Calculate percentage and assign quality score (see REFERENCE.md)

Report: "Git history quality: {score}/10 ({percentage}% conventional commits)"

Step 4: Extract features and architecture decisions

Using methods from REFERENCE.md:

1. Extract feature boundaries from conventional commit scopes 2. Identify architecture decisions (migrations, major dependencies, breaking changes) 3. Find issue references and future work items (TODOs, skipped tests) 4. Identify release boundaries from git tags

Collect findings in structured format for user confirmation.

Step 5: Analyze codebase and existing documentation

1. Use Explore agent to analyze architecture: directory structure, components, frameworks, patterns, entry points, data layer, API layer, testing structure 2. Extract dependencies from manifest files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.) 3. Read and extract from existing documentation: README.md, docs/, ARCHITECTURE.md, DESIGN.md, CONTRIBUTING.md 4. Detect future work: TODOs in code, open GitHub issues, skipped tests

Step 6: Clarify project context with user

Ask for clarifications on:

1. Project purpose (if not clear from README): Present inferred description for confirmation or ask user to provide 2. Target users: Who are the primary users (developers, end users, both)? 3. Feature confirmation: Present {N} features extracted from git for review/prioritization 4. Architecture rationale: For each identified decision, ask what was the main driver 5. Generation confirmation: Show summary with metrics and ask if ready to generate

For confirmation step, present:

• Git history quality: {score}/10
• Features identified: {N}
• Architecture decisions: {N}
• Future work items: {N}
• Proposed documents: PRD, {N} ADRs, {N} PRPs

Step 7: Generate documents

Create directory structure: mkdir -p docs/prds docs/adrs docs/prps

For each document type, use templates and patterns from REFERENCE.md:

1. Generate PRD as docs/prds/project-overview.md

• Use sections and structure from REFERENCE.md
• Include extracted features with priorities and sources
• Mark sections with confidence scores

2. Generate ADRs as docs/adrs/{NNNN}-{title}.md (one per decision)

• Use ADR template from REFERENCE.md
• Include git evidence (commit SHA, date, files changed)
• Mark with confidence score

3. Create ADR index at docs/adrs/README.md

• Table of all ADRs with status and dates
• Link to MADR template for new ADRs

4. Generate PRPs as docs/prps/{feature}.md (one per future work item)

• Use PRP template from REFERENCE.md
• Include source reference and confidence score
• Suggest implementation based on codebase patterns

Step 8: Update manifest and report results

1. Update docs/blueprint/manifest.json with import metadata: timestamp, commits analyzed, confidence scores, generated artifacts

Step 9: Update task registry

Update the task registry entry in docs/blueprint/manifest.json:

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg sha "$(git rev-parse HEAD 2>/dev/null)" \
  --argjson analyzed "${COMMITS_ANALYZED:-0}" \
  --argjson created "${DOCS_GENERATED:-0}" \
  '.task_registry["derive-plans"].last_completed_at = $now |
   .task_registry["derive-plans"].last_result = "success" |
   .task_registry["derive-plans"].context.commits_analyzed_up_to = $sha |
   .task_registry["derive-plans"].context.commits_analyzed_count = $analyzed |
   .task_registry["derive-plans"].stats.runs_total = ((.task_registry["derive-plans"].stats.runs_total // 0) + 1) |
   .task_registry["derive-plans"].stats.items_processed = $analyzed |
   .task_registry["derive-plans"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

2. Create summary report showing:

• Commits analyzed with date range
• Git quality score
• Documents generated (PRD, ADR count, PRP count)
• Sections needing review (confidence < 7)
• Recommended next steps

3. Prompt user for next action:

• Review and refine documents
• Generate project rules from PRD
• Generate workflow commands
• Exit (documents saved)

Agentic Optimizations

---

For detailed templates, git analysis patterns, document generation examples, and error handling guidance, see REFERENCE.md.

blueprint-derive-plans REFERENCE

Reference material for git analysis patterns, document templates, and detailed implementation guidance.

Git Analysis Patterns

Git Quality Scoring

Determine quality score based on conventional commit percentage:

Commit Scope Extraction

# Extract feature boundaries from conventional commit scopes
git log --oneline --format="%s" {scope} | grep -oE "^\w+\(([^)]+)\)" | \
  sed 's/.*(\([^)]*\)).*/\1/' | sort | uniq -c | sort -rn | head -20

For each scope with 3+ commits, record:

• Feature name (scope value)
• Commit count
• Date range (first to last commit)
• Commit types distribution (feat/fix/refactor)

Architecture Decision Detection

# Technology migrations
git log --oneline --format="%s" {scope} | \
  grep -iE "(migrate|switch|replace|upgrade|adopt|move from|move to)" | head -20

# Major dependency changes
git log --oneline --format="%s" {scope} | \
  grep -iE "(add|install|introduce|integrate|remove|drop) .*(library|framework|package|dependency|database|orm)" | head -20

# Breaking changes
git log --oneline --format="%s" {scope} | grep -E "^[a-z]+(\([^)]+\))?!:" | head -20
git log --format="%B" {scope} | grep -iB5 "BREAKING CHANGE:" | head -30

For each identified decision, record:

• What changed (from commit message)
• When (commit date)
• Commit SHA (for reference)
• Confidence: High if explicit, Medium if inferred

Issue References

# Find issue references
git log --oneline --format="%s %b" {scope} | \
  grep -oE "(Fixes|Closes|Resolves|Refs|Related to) #[0-9]+" | \
  sort | uniq -c | sort -rn | head -30

Map issues to features where possible.

Release Boundary Detection

# Find release tags and commits between them
git tag -l | grep -E "^v?[0-9]+\.[0-9]+" | head -20

# Get commits between two releases
git log --oneline {tag1}..{tag2} | head -10

Document Templates

PRD Template

# {Project Name} - Product Requirements Document

**Created**: {date}
**Status**: Retroactive (Generated from history)
**Version**: {latest_tag or "1.0"}
**Import Confidence**: {overall_score}/10

## Executive Summary

### Problem Statement
{Extracted from README or user input}
<!-- confidence: {score}/10 - {source} -->

### Proposed Solution
{Project description from README/analysis}
<!-- confidence: {score}/10 - {source} -->

### Business Impact
{Inferred or from user input}
<!-- confidence: {score}/10 - {source} -->

## Stakeholders & Personas

{From user input or marked as "Needs clarification"}

### User Personas

#### Primary: {Persona from user input}
- **Description**: {description}
- **Needs**: {needs}
- **Goals**: {goals}

## Functional Requirements

### Core Features

| ID | Feature | Description | Priority | Source |
|----|---------|-------------|----------|--------|
| FR-001 | {feature} | {from commits/code} | {P0/P1/P2} | git: {scope}, {commit_count} commits |
| FR-002 | {feature} | {description} | {priority} | git: {scope} |

### Feature Details

#### FR-001: {Feature Name}
- **Commits**: {first_sha}..{last_sha} ({date_range})
- **Related issues**: {issue_refs}
- **Key files**: {main_files}

## Non-Functional Requirements

### Performance
{Inferred from dependencies or marked as "Needs input"}

### Security
{Inferred from auth-related code or marked as "Needs input"}

### Compatibility
{From package.json engines, tsconfig target, etc.}

## Technical Considerations

### Architecture
{From Explore agent analysis}

### Tech Stack
{From dependency analysis}
- Language: {language}
- Framework: {framework}
- Testing: {test_framework}
- Database: {database if detected}

### Dependencies
{Key dependencies from manifest}

## Success Metrics

| Metric | Baseline | Target | Measurement |
|--------|----------|--------|-------------|
| {metric} | {current} | {target} | {how} |

<!-- Most metrics need user input for established projects -->

## Scope

### In Scope
{Inferred from implemented features}

### Out of Scope
{Marked as "Needs user input"}

## Timeline & Phases

### Current Phase: {Inferred from git activity}

### History
| Phase | Focus | Dates | Status |
|-------|-------|-------|--------|
| Initial Development | Core features | {first_commit} - {tag_v1} | Complete |
| {Phase 2} | {inferred} | {dates} | {status} |

---

## Import Metadata

**Generated by**: /blueprint:derive-plans
**Analysis date**: {date}
**Commits analyzed**: {count}
**Date range**: {first_commit_date} to {last_commit_date}
**Git quality score**: {score}/10

### Confidence Summary
| Section | Confidence | Notes |
|---------|------------|-------|
| Executive Summary | {score}/10 | {notes} |
| Features | {score}/10 | {notes} |
| Technical | {score}/10 | {notes} |
| Non-Functional | {score}/10 | {notes} |

### Sections Needing Review
- {list sections with low confidence}

ADR Template

# ADR-{number}: {Decision Title}

**Date**: {commit_date}
**Status**: Accepted (Retroactive)
**Confidence**: {score}/10

## Context

{Inferred from pre-change state or user input}
<!-- This decision was identified from git history. Original context may need clarification. -->

## Decision Drivers

- {driver from user input or inferred}
- {driver 2}

## Considered Options

1. **{Current choice}** - The implemented solution
2. **{Alternative 1}** - Common alternative for this type of decision
3. **{Alternative 2}** - Another common alternative

## Decision Outcome

**Chosen option**: "{Current choice}" because {user-provided rationale or "rationale needs documentation"}.

### Positive Consequences

- {inferred benefit from implementation}
- {benefit 2}

### Negative Consequences

- {known tradeoff if any}
- {limitation if any}

## Evidence

- **Commit**: {sha} - "{commit_message}"
- **Date**: {date}
- **Files changed**: {key files}

---

*Retroactively generated from git history via /blueprint:derive-plans*
*Original commit: {sha} on {date}*

ADR Index Template

# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) documenting significant technical decisions.

**Note**: These ADRs were retroactively generated from git history. Review and enhance rationale sections as needed.

## Index

| ADR | Title | Status | Date | Confidence |
|-----|-------|--------|------|------------|
| [0001](0001-{title}.md) | {title} | Accepted | {date} | {score}/10 |
| [0002](0002-{title}.md) | {title} | Accepted | {date} | {score}/10 |

## Template

New ADRs should follow the [MADR template](https://adr.github.io/madr/).

PRP Template

# PRP: {Feature/Task Name}

**Created**: {date}
**Status**: Suggested
**Source**: {TODO|Issue|Analysis}
**Confidence**: {score}/10

## Goal

{Extracted from TODO comment, issue title, or analysis}

### Why

{Inferred from context or marked as "Needs clarification"}

## Context

### Source Reference

**Origin**: {source_type}
- Location: `{file}:{line}` or Issue #{number}
- Text: "{original_text}"

### Codebase Intelligence

{From Explore agent - related code, patterns to follow}

### Known Gotchas

| Gotcha | Impact | Mitigation |
|--------|--------|------------|
| {identified concern} | {impact} | {suggested approach} |

## Suggested Implementation

{Basic outline based on similar features in codebase}

## TDD Requirements

{Template based on project testing patterns}

### Test Strategy
- Unit tests: {what to test}
- Integration tests: {if applicable}

---

*Suggested future work identified via /blueprint:derive-plans*
*Requires prioritization and detailed planning before execution*

Manifest Update Format

{
  "format_version": "3.0.0",
  "updated_at": "{ISO timestamp}",
  "structure": {
    "has_prds": true,
    "has_adrs": true,
    "has_prps": true
  },
  "import_metadata": {
    "imported_at": "{ISO timestamp}",
    "commits_analyzed": {count},
    "date_range": ["{start}", "{end}"],
    "git_quality_score": {score},
    "features_extracted": {count},
    "decisions_identified": {count},
    "future_work_suggested": {count},
    "overall_confidence": {score}
  },
  "generated_artifacts": [
    {
      "type": "prd",
      "file": "docs/prds/project-overview.md",
      "confidence": {score},
      "source": "import"
    },
    {
      "type": "adr",
      "file": "docs/adrs/0001-{title}.md",
      "confidence": {score},
      "source": "import"
    }
  ]
}

Summary Report Format

Blueprint Import Complete!

**Analysis Summary**
- Commits analyzed: {N} ({date_range})
- Conventional commits: {percentage}%
- Git quality score: {score}/10

**Documents Generated**

PRD: docs/prds/project-overview.md (confidence: {score}/10)
   - Features documented: {N}
   - User clarifications incorporated: {N}

ADRs: {N} decisions documented
   - 0001-{title}.md (confidence: {score}/10)
   - 0002-{title}.md (confidence: {score}/10)
   ...

PRPs: {N} future work items suggested
   - docs/prps/{name}.md (from TODOs)
   - docs/prps/{name}.md (from issues)
   ...

**Needs Review**
{List sections/documents with confidence < 7}

**Next Steps**
1. Review documents marked "needs clarification"
2. Run `/blueprint:generate-rules` to create implementation patterns
3. Run `/blueprint:generate-commands` for workflow automation

Next Action Prompt

After completion, prompt the user with:

question: "Import complete (average confidence: {score}/10). What would you like to do?"
options:
  - label: "Review and refine documents (Recommended)"
    description: "Go through items marked 'needs clarification'"
  - label: "Generate project rules"
    description: "Run /blueprint:generate-rules from the new PRD"
  - label: "Generate workflow commands"
    description: "Run /blueprint:generate-commands for this project"
  - label: "I'm done for now"
    description: "Exit - documents are saved and ready for review"

Based on selection:

• "Review and refine" - Show list of documents needing attention with file paths
• "Generate project rules" - Run /blueprint:generate-rules
• "Generate workflow commands" - Run /blueprint:generate-commands
• "I'm done" - Exit with quick reference

Error Handling

Implementation Tips

• Git history quality matters: Projects with conventional commits produce better results
• User input improves accuracy: Answer clarifying questions to increase confidence scores
• Review low-confidence sections: Focus review effort on sections marked < 7/10
• Iterative refinement: Run import once, then refine documents manually
• Combine with existing docs: If some documentation exists, import will incorporate it