Makefile Review Skill for Claude

Table of Contents

• Quick Start
• When to Use
• Required TodoWrite Items
• Workflow
• Step 1: Map Context (makefile-review:context-mapped))
• Step 2: Dependency Graph (makefile-review:dependency-graph))
• Step 3: Deduplication Audit (makefile-review:dedup-candidates))
• Step 4: Portability Check (makefile-review:tooling-alignment))
• Step 5: Evidence Log (makefile-review:evidence-logged))
• Progressive Loading
• Output Format
• Summary
• Testing

Testing

Run pytest plugins/pensive/tests/skills/test_makefile_review.py to verify review logic.

Makefile Review Workflow

Audit Makefiles for best practices, deduplication, and portability.

Quick Start

/makefile-review

When To Use

• Makefile changes or additions
• Build system optimization
• Portability improvements
• CI/CD pipeline updates
• Developer experience improvements

When NOT To Use

• Creating new Makefiles - use abstract:make-dogfood
• Architecture review - use architecture-review

Required TodoWrite Items

• makefile-review:context-mapped
• makefile-review:dependency-graph
• makefile-review:dedup-candidates
• makefile-review:tooling-alignment
• makefile-review:evidence-logged
• makefile-review:findings-verified

Workflow

Step 1: Map Context (makefile-review:context-mapped)

Confirm baseline:

pwd && git status -sb && git diff --stat

Verification: Run git status to confirm working tree state.

Find Make-related files:

rg -n "^include" -g'Makefile*'
rg --files -g '*.mk'

Document changed targets, project goals, and tooling requirements.

Step 2: Dependency Graph (makefile-review:dependency-graph)

@include modules/dependency-graph.md

Step 3: Deduplication Audit (makefile-review:dedup-candidates)

@include modules/deduplication-patterns.md

Step 4: Portability Check (makefile-review:tooling-alignment)

@include modules/portability-checks.md

Step 5: Evidence Log (makefile-review:evidence-logged)

Use imbue:proof-of-work to record command outputs with file:line references.

Summarize findings:

• Severity (critical, major, minor)
• Expected impact
• Suggested refactors
• Owners and dates for follow-ups

Progressive Loading

Load additional context as needed:

Best Practices & Examples: @include modules/best-practices.md

Plugin Dogfood Checks: @include modules/plugin-dogfood-checks.md - Makefile completeness analysis, target generation, and dogfooding validation.

Output Format

## Summary
Makefile review findings

## Context
- Files reviewed: [list]
- Targets changed: [list]

## Dependency Analysis
[graph and issues]

## Duplication Candidates
### [D1] Repeated command
- Locations: [list]
- Anchor: `verbatim source text at file:line`
- Recommendation: [pattern rule]

## Portability Issues
[cross-platform concerns]

## Missing Targets
- [ ] help
- [ ] format
- [ ] lint

## Recommendation
Approve / Approve with actions / Block

Verify Findings Are Grounded (makefile-review:findings-verified)

Every finding must cite a real location and a verbatim anchor. Write

findings to .review/findings.json and confirm each citation resolves:

python plugins/imbue/scripts/citation_verifier.py \
  --findings .review/findings.json --repo-root .

Drop or label UNVERIFIED any finding the verifier fails (exit 1); only

verified findings enter the report. See Skill(imbue:review-core) Step 5

and Skill(imbue:structured-output) for the schema.

Exit Criteria

• Context mapped
• Dependencies analyzed
• Deduplication reviewed
• Portability checked
• Evidence logged
• Every reported finding carries a Location + verbatim Anchor confirmed

by citation_verifier.py (exit 0), or unverified findings were dropped

or labeled UNVERIFIED

Troubleshooting

Common Issues

No Makefile found

Ensure Makefile or *.mk files exist in the project root or specify paths explicitly.

Include directives not resolved

Run rg -n "^include" -g'Makefile*' to trace include chains manually.