map-feature
Skill0 starsChanged 7 months agoMITView on GitHub
Map what a feature actually touches before building it. Reads the existing codebase, hunts for prior art and reusable pieces, then shows a current→proposed architecture diff (Mermaid) with a reuse-first recommendation, and stops for approval before any code is written. Use before building any non-trivial feature, when you suspect the work is about to over-build or duplicate something that already exists, or to verify the right approach before committing days of effort. This is an adversarial reality-check against the current code — NOT a generative design doc (use /prd or feature-design-assistant for that). Triggers on: "map this feature", "before we build", "is there already something that does this", "what does this feature touch", "architecture for", "don't over-build", "should I build this or reuse", "/map-feature".
In this repository7 other files it gives its agents.
- browseSkill
- debriefSkill
- persona-testSkill
- progressive-summarySkill
- prompt-engineerSkill
- screen-reviewSkill
- spec-kitSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Read code, don't infer from names: Every node in the current-state diagram must correspond to code you actually opened and traced.
- Very specific: line 41
Phase 2 is mandatory: Before proposing *any* new module/file/dependency, you must state what you grepped for and what you found.
- Distinctive: line 53
If the feature is ambiguous or you can't tell where it lands, ask — don't guess your way into mapping the wrong part of the codebase.
- Distinctive: line 58
Follow imports and call chains outward.
- Distinctive: line 71
If you cannot populate this from code you actually read, say so and go read more before continuing.
- Distinctive: line 83
If the search genuinely turns up nothing reusable, state that plainly — that's a real finding that justifies net-new.
- Distinctive: line 112
After presenting the verdict, save the analysis as a Markdown note.
- Distinctive: line 115
Explicit path: If the user gave a path/location (as an argument or in conversation), use it.
- Very specific: line 118
If <repo>/docs/ exists → save to <repo>/docs/feature-maps/<feature-slug>.md (the feature-maps/ subfolder groups these and keeps real docs …
- Very specific: line 121
If <repo>/docs/ does not exist → stop and ask the user: create docs/feature-maps/, give a different path, or skip the note.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Map Feature
A read-only, reuse-first architecture gate. Before building a feature, map what it actually touches in the real code, find what already solves part or all of it, and show a current→proposed architecture diff. End with a verdict and a saved note. Write no feature code until the user approves.
The point is not the diagram — it's catching the failure mode where an agent builds something new when it only needed to connect two things that already exist, or pulls in a dependency the project already has. The diagram is how the user eyeballs whether the exploration was deep enough: a thin or wrong current-state map is the tell that the code wasn't actually read.
When to Use
/map-feature [feature description] [optional: explicit save path]- "Before we build X, map it" / "is there already something that does this?"
- Any time the next step would be building a non-trivial feature and reuse vs. net-new is unclear.
Skip it for trivial one-file changes — this is for work where over-building would cost real time.
Hard Rules (read first)
These exist because the default behavior is shallow pattern-matching. Do not skip them.
- Read code, don't infer from names. Every node in the current-state diagram must correspond to code you actually opened and traced. No guessing architecture from file or folder names.
- Phase 2 is mandatory. Before proposing any new module/file/dependency, you must state what
you grepped for and what you found. "I searched for
Xand found nothing" is a valid result; silently skipping the search is not. - Bias hard toward reuse. Connecting or extending existing pieces is the default. Net-new is the exception and must be justified with a concrete reason reuse can't work.
- Stop before building. This skill produces a verdict and a note. It does not write feature code. Hand control back to the user for the go/no-go.
Workflow
Phase 0 — Scope
State, in one or two lines: what the feature is, and which subsystem(s) it plausibly touches. If the feature is ambiguous or you can't tell where it lands, ask — don't guess your way into mapping the wrong part of the codebase.
Phase 1 — Map current state (from real code)
- Identify the entry points into the affected area (routes, handlers, commands, screens, jobs).
- Follow imports and call chains outward. Inventory the existing modules, services, and data flows that the feature will sit near.
- Render it as a Mermaid
graph LR(orTD) diagram. Keep node labels to real component names from the code.
graph LR
Client --> API[FastAPI]
API --> Queue[SQS]
Queue --> Worker
Worker --> DB[(DynamoDB)]If you cannot populate this from code you actually read, say so and go read more before continuing.
Phase 2 — Hunt for prior art (the step that earns this skill its keep)
- Grep the codebase for existing implementations of the feature's concept (the verb/noun of the feature — e.g. "retry", "cache", "auth", "rate limit", "webhook").
- Read the dependency manifest —
package.json,requirements.txt/pyproject.toml,Package.swift,go.mod,Cargo.toml, etc. — for a library already pulling that weight. - Produce an explicit "Already exists" list:
- what existing code/dependency solves part or all of the need, and
- the connection the user would actually make instead of writing new code
(e.g. "call
retry_policyfromcore/net.pyinstead of adding a new retry loop").
If the search genuinely turns up nothing reusable, state that plainly — that's a real finding that justifies net-new.
Phase 3 — Propose post-feature state (reuse-biased)
Offer up to two options when both are real:
- Minimal — extend or connect what already exists. Fewest new nodes/edges. This is the default recommendation unless it genuinely doesn't work.
- Net-new — only when reuse can't cover it. Must include the specific reason why.
Phase 4 — Diff + verdict
- Render the proposed state as a Mermaid diagram with new nodes/edges marked, e.g.:
graph LR
Client --> API[FastAPI]
API --> Queue[SQS]
Queue --> Worker
Worker --> DB[(DynamoDB)]
Worker -.NEW.-> Cache[(Redis)]- Call out:
- Unnecessary additions the naive approach would have introduced.
- Duplicate dependencies — anything you'd have added that the project already has.
- Give a clear recommendation (Minimal vs Net-new) with reasoning, then stop. Ask the user for the go-ahead.
Saving the Note
After presenting the verdict, save the analysis as a Markdown note.
Location resolution (in order):
- Explicit path. If the user gave a path/location (as an argument or in conversation), use it. No detection.
- Repo
docs/folder. Otherwise find the repo root:git rev-parse --show-toplevel.- If
<repo>/docs/exists → save to<repo>/docs/feature-maps/<feature-slug>.md(thefeature-maps/subfolder groups these and keeps real docs uncluttered; creating that one subfolder inside an existingdocs/is fine). - If
<repo>/docs/does not exist → stop and ask the user: createdocs/feature-maps/, give a different path, or skip the note. Never silently create a top-leveldocs/folder (anti-bloat rule).
- If
- Not in a git repo (e.g. run from the vault or a loose folder) → same fallback: ask where to put it. Never guess.
Note contents:
- Frontmatter:
Populate--- feature: <feature name> created: <YYYY-MM-DD> status: proposed verdict: <minimal | net-new> session: <id> session-project: <short-path> ---session/session-projectfrom~/.claude/.current-sessionper global rules (SESSION_ID=$(grep ^SESSION_ID= ~/.claude/.current-session | cut -d= -f2-)and the CWD line, short-path = CWD with~/Documents/stripped). - Body, in order:
- Scope
- Current-state Mermaid diagram
- "Already exists" findings
- Proposed-state Mermaid diagram (diff highlighted)
- Verdict + reasoning
Confirm the saved path to the user.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

