Blueprint Derive Rules

/blueprint:derive-rules

Extract project decisions from git commit history and codify them as Claude rules. Newer commits override older decisions when conflicts exist.

Use case: Derive implicit project patterns from git history to establish consistent AI-assisted development guidelines.

Usage: /blueprint:derive-rules [--since DATE] [--scope SCOPE]

When to Use This Skill

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
• Conventional commits %: !git log --format="%s"
• Existing rules in default location: !find . -path '*/.claude/rules/*' -maxdepth 3 -name "*.md" -type f
• Existing rules in blueprint subdir: !find . -path '*/.claude/rules/blueprint/*' -maxdepth 4 -name "*.md" -type f

Parameters

Parse $ARGUMENTS:

• --since DATE: Analyze commits from specific date (e.g., --since 2024-01-01)
• --scope SCOPE: Focus on specific area (e.g., --scope api, --scope testing)

Execution

Execute the complete git-to-rules derivation workflow:

Step 0: Resolve the output path

Read structure.generated_rules_path from docs/blueprint/manifest.json (default .claude/rules/):

RULES_DIR=$(jq -r '.structure.generated_rules_path // ".claude/rules/"' docs/blueprint/manifest.json)
mkdir -p "$RULES_DIR"

Use $RULES_DIR for all subsequent reads/writes and conflict checks. Hand-written files in the parent .claude/rules/ are intentionally invisible to this skill (issue #1043).

Step 1: Verify prerequisites

1. If not a git repository → Error: "This directory is not a git repository"
2. If Blueprint not initialized → Suggest /blueprint:init first
3. If few commits (< 20) → Warn: "Limited commit history; derived rules may be incomplete"

Step 2: Analyze git history quality

1. Calculate total commits in scope
2. Calculate conventional commits percentage
3. Report quality: Higher % = higher confidence in extracted rules
4. Parse --since and --scope flags to determine analysis range

Step 3: Extract decision-bearing commits

Use parallel agents to analyze git history efficiently (see REFERENCE.md):

• Agent 1: Analyze refactor: commits for code style patterns
• Agent 2: Analyze fix: commits for repeated issue types
• Agent 3: Analyze feat!: and BREAKING CHANGE: commits for architecture decisions
• Agent 4: Analyze chore: and build: commits for tooling decisions

Consolidate findings by domain (code-style, testing, api-design, etc.), chronologically (newest first), and by frequency (most common wins).

Step 4: Resolve conflicts

When multiple commits address the same topic:

1. Detect conflicts using pattern matching: git log --format="%H|%ai|%s" | grep "{topic}"
2. Apply resolution strategy:
   • Newer overrides older: Latest decision wins
   • Higher frequency wins: If 5 commits say X and 1 says Y, X wins
   • Breaking changes override: feat!: trumps regular commits
3. Mark overridden decisions as "superseded" with reference to newer decision
4. Confirm significant decisions with user via AskUserQuestion

Step 5: Generate rules in $RULES_DIR

For each decision, generate rule file using template from REFERENCE.md. Write each file to $RULES_DIR/<filename>.md (the configured structure.generated_rules_path):

1. Extract source commit, date, type

2. Determine confidence level (High/Medium/Low based on commit frequency and clarity)

3. Generate actionable rule statement

4. Include code examples from commit diffs

5. Reference any superseded earlier decisions

6. REQUIRED: scope every generated rule via paths: frontmatter unless the rule genuinely applies everywhere. Rules without paths: load on every session and pollute context for unrelated work. Pick paths: from the source signal:

   Signal	Source	paths: value
   Rule body cites a specific file via "patterns extracted from <path>"	Step 3 / 4 conflict resolution	Glob over that file's directory: <dir>/**/*.<ext>
   Rule was derived from chore(deps) / build: commits	Tooling-decision agent	Lockfiles + manifests: package.json, pyproject.toml, Cargo.toml, go.mod, *.lock, biome.json, etc.
   Rule references a language (refactor: + JS-only code blocks)	Code-style agent	Language Glob: **/*.{js,jsx,ts,tsx}, **/*.py, **/*.rs
   Rule is about tests	Test-strategy agent	**/*.{test,spec}.*, tests/**/*, test/**/*
   Rule is about API endpoints	API-design agent	src/{api,routes}/**/*, **/*controller*, **/*handler*
   Rule is about documentation	Docs agent	docs/**, **/*.md
   Rule restates global project context (already in CLAUDE.md)	any	Do not emit — that's CLAUDE.md's job; abort the rule
   Rule genuinely applies to every file (e.g. universal error-handling philosophy, security mindset)	Rare	Omit paths: deliberately and note "global rule" in the rule body

   Default to scoping. The auto-derived starting point: take every code block in the rule body, collect the file extensions / directory roots they reference, and emit those as paths:. Verify the resulting glob set actually matches files in the working tree before writing — an empty match list means the inferred scope is wrong; re-derive.

Generate separate rule files by category (see REFERENCE.md for canonical filenames and default paths: per category):

• code-style.md, testing-standards.md, api-conventions.md, error-handling.md, dependencies.md, security-practices.md

Step 6: Handle conflicts with existing rules

Check for conflicts with existing rules only under $RULES_DIR (never the parent .claude/rules/, which may contain hand-authored content unrelated to blueprint):

1. If conflicts found → Ask user: Git-derived overrides existing rule, or keep existing?
2. Apply user choice: Update, merge, or keep separate
3. Document conflict resolution in rule file

Step 7: 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 processed "${COMMITS_ANALYZED:-0}" \
  --argjson created "${RULES_DERIVED:-0}" \
  '.task_registry["derive-rules"].last_completed_at = $now |
   .task_registry["derive-rules"].last_result = "success" |
   .task_registry["derive-rules"].context.commits_analyzed_up_to = $sha |
   .task_registry["derive-rules"].stats.runs_total = ((.task_registry["derive-rules"].stats.runs_total // 0) + 1) |
   .task_registry["derive-rules"].stats.items_processed = $processed |
   .task_registry["derive-rules"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

Step 8: Update manifest and report

1. Update docs/blueprint/manifest.json with derived rules metadata: timestamp, commits analyzed, rules generated, source commits
2. Generate completion report showing:
   • Commits analyzed (count and date range)
   • Conventional commits percentage
   • Rules generated by category
   • Confidence scores per rule
   • Any conflicts resolved
3. Prompt user for next action: Review rules, execute derived development workflow, or done

Agentic Optimizations

For git analysis patterns, rule templates, conflict resolution, and detailed procedures, see REFERENCE.md.