blueprint-derive-tests

created	"2026-02-22T00:00:00.000Z"
modified	"2026-06-18T00:00:00.000Z"
reviewed	"2026-06-10T00:00:00.000Z"
description	Derive test regression plans from git history by finding commits lacking tests. Use when finding untested bug fixes, coverage gaps, or generating a test backlog.
args	[--since DATE] [--quick] [--scope AREA]
argument-hint	--since 2024-06-01 for date range, --quick for last 50, --scope auth for specific area
allowed-tools	Read, Write, Glob, Grep, Bash, AskUserQuestion, Task
model	opus
name	blueprint-derive-tests

/blueprint:derive-tests

Analyze git history to identify fix and feature commits lacking corresponding test changes, then generate a structured Test Regression Plan (TRP) document as a prioritized test backlog.

Use case: Systematically close test coverage gaps by mining commit history for bug fixes and features that shipped without regression tests.

When to Use This Skill

Use this skill when...	Use alternative when...
Bug fixes ship without regression tests	You need to run existing tests (/test:run)
Want a prioritized test backlog from history	Writing tests for a specific feature (manual TDD)
Onboarding a project and assessing test health	Checking current test coverage metrics
Need to find which fixes lack test coverage	Designing a test strategy from scratch (/test:architecture)

Context

• Git repository: !git rev-parse --git-dir
• Blueprint initialized: !find . -path '*/docs/blueprint/*' -maxdepth 3 -name 'manifest.json' -type f
• Total commits: !git rev-list --count HEAD
• Test framework: !find . -maxdepth 3 \( -name 'vitest.config.*' -o -name 'jest.config.*' -o -name 'pytest.ini' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \) -type f -print -quit
• Test files: !find . -maxdepth 4 -type f \( -name '*.test.*' -o -name '*.spec.*' -o -name 'test_*' -o -name '*_test.*' \) -print
• Conventional commits sample: !git log --format="%s" --max-count=10

Parameters

Parse these from $ARGUMENTS:

• --quick: Fast scan (last 50 commits only)
• --since DATE: Analyze commits from specific date (e.g., --since 2024-06-01)
• --scope AREA: Filter to commits touching a specific area/scope (e.g., --scope auth)

Default behavior without flags: Analyze last 200 commits.

For detailed templates, severity matrix, and test mapping rules, see REFERENCE.md.

Execution

Execute this test regression plan derivation workflow:

Step 1: Verify prerequisites

Check context values above:

1. If git repository is empty → 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 is empty → Ask user: "Blueprint not initialized. Initialize now (Recommended) or continue without manifest tracking?"
   • If "Initialize now" → Use Task tool to invoke /blueprint:init, then continue
   • If "Continue without" → Skip manifest updates in Step 7

Step 2: Determine analysis scope

Parse $ARGUMENTS for --quick, --since, and --scope:

1. If --quick → scope = last 50 commits
2. If --since DATE → scope = commits from DATE to now
3. If --scope AREA → filter commits to those with scope matching AREA or touching files in AREA directory
4. Otherwise → scope = last 200 commits

Store scope parameters for git log commands in subsequent steps.

Step 3: Detect test infrastructure

Scan for test framework and conventions:

1. Identify test framework from context (vitest, jest, pytest, cargo test, go test)
2. Detect test file naming convention:
   • *.test.ts, *.spec.ts (JS/TS)
   • test_*.py, *_test.py (Python)
   • *_test.rs, tests/ directory (Rust)
   • *_test.go (Go)
3. Map source directories to test directories (e.g., src/ → tests/, src/ → src/__tests__/)
4. Record framework, naming pattern, and directory mapping for Step 5

If no test framework detected → Warn user, continue with file-based detection only.

Step 4: Classify commits and detect coverage gaps

Run the helper. It owns the deterministic core: classifying fix:/feat: commits from git log, detecting whether each commit carried an inline test-file change (git show --name-only), and assigning a severity via the fixed matrix (fix: + no inline test → CRITICAL; feat: + no inline test → MEDIUM; any commit shipping a test → COVERED). Pass --limit to cap the scan (default 200; pass --limit 50 for --quick):

bash "${CLAUDE_SKILL_DIR}/scripts/blueprint-derive-tests.sh" --home-dir "$HOME" --project-dir "$(pwd)"

Parse STATUS= and ISSUES: from the output. FIX_COMMITS/FEAT_COMMITS are the classification counts; GAPS_CRITICAL/GAPS_MEDIUM/GAPS_TOTAL are the coverage gaps; each coverage_gap issue carries SHA=, TYPE=, SEVERITY=, and SUBJECT= for the TRP table. STATUS=ERROR means at least one CRITICAL (untested fix) gap.

The script's inline-test detection and base severity (CRITICAL/MEDIUM) are the deterministic floor. When you need the finer High/Low tiers, nearby-test-commit softening, or the per-language source-to-test mapping, apply the modifiers from REFERENCE.md and the mapping rules in REFERENCE.md. For --since/--scope filtering, narrow the git scope with the commands in REFERENCE.md before reading the gap set.

Step 6: Generate TRP document

TRPs live at the top level under docs/trps/ — not docs/blueprint/trps/. This matches the sibling derive-* skills' top-level layout. Never write TRPs under docs/blueprint/; that path is reserved for blueprint machinery.

1. Create output directory: mkdir -p docs/trps
2. Determine TRP ID:
   • If manifest exists, read id_registry.last_trp, increment by 1
   • Otherwise start at TRP-001
3. Generate slug from scope or date range (e.g., regression-gaps-2024-q3)
4. Write TRP document to docs/trps/{slug}.md using template from REFERENCE.md

Include in the document:

• YAML frontmatter with id, status: Active, scope, date_range, commits_analyzed
• Executive summary with gap counts by severity
• Detailed gap table: commit SHA, subject, severity, affected files, suggested test type
• Recommended test creation order (Critical first, then High, etc.)
• Suggested test type per gap (see REFERENCE.md)

Step 7: Update manifest

If Blueprint is initialized:

1. Update id_registry.last_trp with the new TRP number
2. Register the document in id_registry.documents:

   {
     "TRP-NNN": {
       "path": "docs/trps/{slug}.md",
       "title": "{TRP title}",
       "status": "Active",
       "created": "{date}"
     }
   }
   

3. Update task registry:

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

Step 8: Report results and suggest next actions

Print summary:

Test Regression Plan Generated!

**Analysis Summary**
- Commits analyzed: {N} ({date_range})
- Fix commits found: {N}
- Feature commits found: {N}

**Coverage Gaps Found**
- Critical: {N} (fix commits with no tests at all)
- High: {N} (fix commits with stale test files)
- Medium: {N} (feature commits missing tests)
- Low: {N} (feature commits with nearby tests)

**Document**: docs/trps/{slug}.md (TRP-{NNN})

**Top Priority Gaps**
1. {commit subject} — {severity} — {affected file}
2. {commit subject} — {severity} — {affected file}
3. {commit subject} — {severity} — {affected file}

Prompt user for next action:

• "Create PRPs for top-priority gaps (Recommended)" — Generate PRP documents for Critical/High gaps
• "Review the TRP document" — Open the generated TRP for manual review
• "Run again with different scope" — Re-run with --since or --scope
• "Done for now" — Exit with document saved

Agentic Optimizations

Context	Command
Fix commits only	git log --format="%H %s" | grep -E "^[a-f0-9]+ fix"
Check test in commit	git diff-tree --no-commit-id --name-only -r {SHA} | grep -E "test|spec"
Files changed	git diff-tree --no-commit-id --name-only -r {SHA}
Fast scan	Use --quick for last 50 commits
Scope filter	Use --scope auth to limit to specific area

---

For detailed templates, severity classification matrix, test mapping rules, and error handling, see REFERENCE.md.