/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

Use this skill when...

Use alternative when...

Project has git history but no PRDs/ADRs/PRPs

Starting a brand new project with no history

Onboarding an established project to Blueprint

Creating a fresh PRD from scratch with user guidance

Need to extract features from commit history

Project lacks conventional commits and clear history

Want to document architecture decisions retroactively

Decisions are already fully documented

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:

If git repository = "NO" → Error: "This directory is not a git repository. Run from project root."

If total commits = "0" → Error: "Repository has no commit history"

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

:

If

--quick

flag present → scope = last 50 commits

If

--since DATE

present → scope = commits from DATE to now

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:

Count total commits:

git log --oneline {scope} | wc -l

Count conventional commits:

git log --format="%s" {scope} | grep -cE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(?.*)?:" || echo 0

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

:

Extract feature boundaries from conventional commit scopes

Identify architecture decisions (migrations, major dependencies, breaking changes)

Find issue references and future work items (TODOs, skipped tests)

Identify release boundaries from git tags

Collect findings in structured format for user confirmation.

Step 5: Analyze codebase and existing documentation

Use Explore agent to analyze architecture: directory structure, components, frameworks, patterns, entry points, data layer, API layer, testing structure

Extract dependencies from manifest files (package.json, pyproject.toml, Cargo.toml, go.mod, etc.)

Read and extract from existing documentation: README.md, docs/, ARCHITECTURE.md, DESIGN.md, CONTRIBUTING.md

Detect future work: TODOs in code, open GitHub issues, skipped tests

Step 6: Clarify project context with user

Ask for clarifications on:

Project purpose

(if not clear from README): Present inferred description for confirmation or ask user to provide

Target users

Who are the primary users (developers, end users, both)?

Feature confirmation

Present {N} features extracted from git for review/prioritization

Architecture rationale

For each identified decision, ask what was the main driver
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 : 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 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 Create ADR index at docs/adrs/README.md Table of all ADRs with status and dates Link to MADR template for new ADRs 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 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 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 Prompt user for next action: Review and refine documents Generate project rules from PRD Generate workflow commands Exit (documents saved) Agentic Optimizations Context Command Check git status git rev-parse --git-dir 2>/dev/null && echo "YES" || echo "NO" Count commits git rev-list --count HEAD 2>/dev/null || echo "0" Conventional commits count git log --format="%s" | grep -cE "^(feat|fix|docs)" || echo 0 Extract scopes git log --format="%s" | grep -oE '([^)]+)' | sort | uniq -c Fast analysis Use --quick flag for last 50 commits only For detailed templates, git analysis patterns, document generation examples, and error handling guidance, see REFERENCE.md .

blueprint-derive-plans

安装