/blueprint:derive-tests Skill

/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 docs/blueprint -maxdepth 1 -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:

If git repository is empty → 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 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:

If --quick → scope = last 50 commits
If --since DATE → scope = commits from DATE to now
If --scope AREA → filter commits to those with scope matching AREA or touching files in AREA directory
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:

Identify test framework from context (vitest, jest, pytest, cargo test, go test)
Detect test file naming convention:
- *.test.ts, *.spec.ts (JS/TS)
- test_*.py, *_test.py (Python)
- *_test.rs, tests/ directory (Rust)
- *_test.go (Go)
Map source directories to test directories (e.g., src/ → tests/, src/ → src/__tests__/)
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: Extract and classify commits

Extract fix and feature commits within scope:

Primary targets — fix: commits (highest priority for regression tests):

git log --format="%H %s" {scope} | grep -E "^[a-f0-9]+ fix(\(.*\))?:"

Secondary targets — feat: commits (should have accompanying tests):

git log --format="%H %s" {scope} | grep -E "^[a-f0-9]+ feat(\(.*\))?:"

Fallback — If conventional commit percentage < 20%, use keyword detection:

git log --format="%H %s" {scope} | grep -iE "(fix|bug|hotfix|patch|resolve|correct)"

For each commit, record: SHA, subject, date, files changed, scope (if conventional).

Step 5: Analyze test coverage gaps

For each commit from Step 4, check for corresponding tests:

Inline test changes — Did the same commit modify test files?

git diff-tree --no-commit-id --name-only -r {SHA} | grep -E "(test|spec|_test\.|\.test\.)"

Nearby test commits — Within 5 commits after the fix, was a test commit added?

git log --format="%H %s" {SHA}..{SHA~5} | grep -iE "^[a-f0-9]+ test(\(.*\))?:|add.*test|test.*for"

Test file exists — For each modified source file, does a corresponding test file exist? Use the source-to-test mapping from Step 3 (see REFERENCE.md for rules per language).

Classify each gap using the severity matrix from REFERENCE.md:

| Severity | Criteria | |----------|----------| | Critical | fix: commit, no test changes, no test file exists for modified source | | High | fix: commit, no inline test changes but test file exists (test not updated) | | Medium | feat: commit, no test changes, core module affected | | Low | feat: commit, no inline tests but nearby test commit exists |

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.

Create output directory: mkdir -p docs/trps
Determine TRP ID:
- If manifest exists, read id_registry.last_trp, increment by 1
- Otherwise start at TRP-001
Generate slug from scope or date range (e.g., regression-gaps-2024-q3)
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:

Update id_registry.last_trp with the new TRP number

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

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.

Agent Skills: /blueprint:derive-tests

Install this agent skill to your local

Skill Files