mine-design

When to use this skill

Snapshot-based design decisions for any codebase. Extract the reasoning behind current architectural choices, trade-offs made, and non-obvious system behaviors that live in the code itself — not in commit messages. Produce _analysis/design.md.

---

Step 1 — Orient

Check if _analysis/index.md already exists:

test -f _analysis/index.md && echo "FOUND" || echo "NOT_FOUND"

If _analysis/index.md exists: Also check for cluster files:

ls _analysis/cluster_*.md 2>/dev/null

Then ask the user:

"Found existing analysis files in _analysis/:

• index.md {- cluster_*.md (list found files, if any)}

Use these for orientation, or run a fresh codebase scan? (Files may be outdated if the code has changed.)"

• Use existing → Read _analysis/index.md. It contains the directory map, framework, entry points, and key file registry. Use it as your structural map and skip the bash commands below — go directly to the _analysis/directives.md check.
• Fresh scan → Run the bash commands below.

If _analysis/index.md does not exist: Run the following to build a structural picture from scratch:

cat README.md 2>/dev/null || cat readme.md 2>/dev/null
cat CLAUDE.md 2>/dev/null
cat package.json 2>/dev/null || cat go.mod 2>/dev/null || cat requirements.txt 2>/dev/null || cat Cargo.toml 2>/dev/null
ls -1

Check if _analysis/directives.md already exists. If it does, skim it to note what subsystems it covers — you'll avoid producing directive-style content (imperative rules from git history) in this analysis.

---

Step 2 — Discover subsystems

From the directory structure and README, identify 4–8 major subsystems or concerns. Before proposing clusters, read at least one entry-point file (main file, index, CLI root, or server start) to confirm the runtime structure matches the directory structure.

If the user chose to use existing files in Step 1 and cluster files were found, skim them to extract subsystem names and their assigned files. Use these as the starting point — adjust or merge only where the cluster divisions do not map cleanly to design concerns.