home / skills / athola / claude-night-market / makefile-review

makefile-review skill

safe

This skill audits and optimizes makefiles for portability and deduplication, helping you improve build reliability and reduce duplication.

npx playbooks add skill athola/claude-night-market --skill makefile-review

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

4.8 KB

---
name: makefile-review
description: 'Use this skill for Makefile audit and optimization. Use when auditing
  Makefiles, reviewing build system, checking portability, eliminating recipe duplication.
  Do not use when creating new Makefiles - use abstract:make-dogfood. DO NOT use when:
  architecture review - use architecture-review.'
category: build
tags:
- makefile
- build
- make
- portability
- automation
tools:
- dependency-mapper
- dedup-finder
- portability-checker
usage_patterns:
- makefile-audit
- build-optimization
- portability-review
- deduplication
complexity: intermediate
estimated_tokens: 150
progressive_loading: true
dependencies:
- pensive:shared
- imbue:evidence-logging
modules:
- dependency-graph
- deduplication-patterns
- portability-checks
- best-practices
---
## Table of Contents

- [Quick Start](#quick-start)
- [When to Use](#when-to-use)
- [Required TodoWrite Items](#required-todowrite-items)
- [Workflow](#workflow)
- [Step 1: Map Context (`makefile-review:context-mapped`)](#step-1:-map-context-(makefile-review:context-mapped))
- [Step 2: Dependency Graph (`makefile-review:dependency-graph`)](#step-2:-dependency-graph-(makefile-review:dependency-graph))
- [Step 3: Deduplication Audit (`makefile-review:dedup-candidates`)](#step-3:-deduplication-audit-(makefile-review:dedup-candidates))
- [Step 4: Portability Check (`makefile-review:tooling-alignment`)](#step-4:-portability-check-(makefile-review:tooling-alignment))
- [Step 5: Evidence Log (`makefile-review:evidence-logged`)](#step-5:-evidence-log-(makefile-review:evidence-logged))
- [Progressive Loading](#progressive-loading)
- [Output Format](#output-format)
- [Summary](#summary)
- [Testing](#testing)

## Testing

Run `pytest plugins/pensive/tests/skills/test_makefile_review.py` to verify review logic.
- [Context](#context)
- [Dependency Analysis](#dependency-analysis)
- [Duplication Candidates](#duplication-candidates)
- [[D1] Repeated command](#[d1]-repeated-command)
- [Portability Issues](#portability-issues)
- [Missing Targets](#missing-targets)
- [Recommendation](#recommendation)
- [Exit Criteria](#exit-criteria)


# Makefile Review Workflow

Audit Makefiles for best practices, deduplication, and portability.

## Quick Start

```bash
/makefile-review
```
**Verification:** Run the command with `--help` flag to verify availability.

## 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

1. `makefile-review:context-mapped`
2. `makefile-review:dependency-graph`
3. `makefile-review:dedup-candidates`
4. `makefile-review:tooling-alignment`
5. `makefile-review:evidence-logged`

## Workflow

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

Confirm baseline:
```bash
pwd && git status -sb && git diff --stat
```
**Verification:** Run `git status` to confirm working tree state.

Find Make-related files:
```bash
rg -n "^include" -g'Makefile*'
rg --files -g '*.mk'
```
**Verification:** Run the command with `--help` flag to verify availability.

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:evidence-logging` 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`

## Output Format

```markdown
## Summary
Makefile review findings

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

## Dependency Analysis
[graph and issues]

## Duplication Candidates
### [D1] Repeated command
- Locations: [list]
- Recommendation: [pattern rule]

## Portability Issues
[cross-platform concerns]

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

## Recommendation
Approve / Approve with actions / Block
```
**Verification:** Run the command with `--help` flag to verify availability.

## Exit Criteria

- Context mapped
- Dependencies analyzed
- Deduplication reviewed
- Portability checked
- Evidence logged
## Troubleshooting

### Common Issues

**Command not found**
Ensure all dependencies are installed and in PATH

**Permission errors**
Check file permissions and run with appropriate privileges

**Unexpected behavior**
Enable verbose logging with `--verbose` flag

Overview

This skill audits and optimizes Makefiles to improve maintainability, reduce duplication, and increase portability. It guides a focused review: mapping context, building dependency graphs, identifying duplicate recipes, checking tooling alignment, and logging evidence for follow-up. Use it to produce actionable recommendations and an evidence-backed remediation plan.

How this skill works

I inspect the repository state and locate Makefiles and included .mk files, then map changed targets and project constraints. I generate a dependency graph of targets, flag repeated recipes and deduplication candidates, and run portability checks against common shells and tools. Finally I produce an evidence log with severity, impact, suggested refactors, and owner/date follow-ups.

When to use it

After Makefile changes or pull requests touching build targets
When optimizing or simplifying an existing build system
Before updating CI/CD pipelines that run Make targets
To improve cross-platform portability and developer experience
When tracking down flaky or slow build steps

Best practices

Start by mapping context: record git status and changed Makefile lines before edits
Prefer pattern rules and variables to repeated literal commands to reduce maintenance
Keep explicit minimal dependencies for each target to avoid hidden rebuilds
Favor POSIX-compatible shell constructs and check tool availability for portability
Log command outputs with file:line references as evidence for recommendations

Example use cases

Audit a PR that adds several new build targets to ensure no duplication or missing deps
Consolidate repeated install/test/build commands into reusable pattern rules or phony targets
Identify portability issues (bash-only constructs, GNU make features) before CI rollout
Produce a remediation plan with owner assignments after an automated review run
Verify that help/format/lint targets exist and behave consistently across environments

FAQ

What inputs do you need to run a review?

A checkout of the repository with Makefiles present and access to the git working tree; running the review from the repo root yields best results.

Can you create new Makefiles from scratch?

No. This skill focuses on audit and optimization. For creating new Makefiles use the dedicated make-dogfood workflow.