Every change has a nature.
Know it before you make it.
A three-layer system that discovers how your project changes, classifies each request, and routes to the right methodology. Fully generic. Entirely opt-in.
The problem with "just fix it"
When you tell Claude "fix this page" or "make it work on mobile," it picks one approach and runs with it. But your request might involve three different types of changes, each with its own constraints and risk.
Wrong approach
Claude treats a CSS specificity battle like a simple style addition. The fix breaks five other elements.
Lost context
A compound change needs three ordered steps. By step two, the constraints from step one are forgotten.
Repeated discovery
You explain the same gotchas every conversation. Last week's learnings don't carry forward.
How it works
Three layers, each manually triggered. Nothing intercepts your normal workflow.
Populator
Run once per project. Scans your codebase, git history, learnings docs, and memory files. Discovers the recurring types of changes you actually make.
Identifier
Run per task. Reads your request, checks the taxonomy and semantic map, classifies the nature(s) of change. Writes an execution plan with per-step context.
Executor
Run per step. Follows the nature-specific methodology: audit, discover, implement, verify. Updates the semantic map after every change.
Entirely opt-in. Want to just fix a bug directly? Do it. The framework only activates when you explicitly invoke it.
When to use it — and when not to
check_circle USE WHEN
merge_type Compound changes
Multiple natures with ordering constraints. The identifier breaks it into steps with handoffs.
explore Unfamiliar codebase
The populator audits the project and tells you what kinds of changes have been made and what gotchas exist.
shield High-risk changes
Responsive CSS overrides, cross-file refactors, dependency changes. Identifier flags risk, executor provides guardrails.
school Capture learnings
Re-run the populator after new work. It discovers patterns, updates executors, promotes natures to global.
cancel SKIP WHEN
edit_note Simple and obvious
Typo fix, variable rename, one-liner. Three layers for one line is pure overhead.
science Exploring or prototyping
Rapid iteration. The classify-plan-execute cycle is too slow for exploratory work.
task_alt You already know the approach
Skip the identifier. Run the executor directly or just make the edit.
fiber_new Brand new project
The populator needs evidence. On a fresh project, start working first, populate later.
Rule of thumb: If you can picture exactly what will change — skip the framework. If you pause and think "where do I even start?" — that's when the identifier earns its keep.
touch_app How to invoke each layer
| Layer | When | Say this | You get |
|---|---|---|---|
| radar Populator | Once per project | "Run the nature populator" | Taxonomy, maps, executors |
| category Identifier | Per task | "Identify the nature: [request]" | Classification, plan |
| build Executor | Per step | "Run /[executor] on [file]" | Modified file, report |
| collections_bookmark Library | Anytime | "Show me the nature library" | All natures index |
The framework in action
Three real scenarios with time estimates and realistic expectations.
"Make the dashboard charts work on mobile"
A SingleFile-saved portal page. Charts exist but are empty, a browser extension sidebar is injected, and the layout breaks below 992px.
Populator ran earlier. Taxonomy has 7 natures. Semantic map shows Highcharts v12.1.2, MUI classes, 4 empty chart divs.
schedule 0 min
Classifies as compound: Excision + Data Hydration + Responsive Adaptation. Writes execution-plan.md with 3 ordered steps.
schedule ~2 min
3 steps: Remove sidebar → init Highcharts → override chart widths for mobile (using field guide).
schedule ~10 min total
Without the framework: Claude would try all three at once, miss the removal step, use the wrong Highcharts API, and skip the CSS specificity field guide.
"Add auth middleware to the API routes"
FastAPI project. Populator ran last week, discovered "Middleware Integration" from 3 past commits + README gotcha about ordering.
Middleware Integration, module-level. Reads module map for dependency order. Risk: MEDIUM (middleware ordering affects all routes).
schedule ~1 min
Executor knows middleware ordering: places auth after CORS, before route handlers. Verifies all existing routes still respond.
schedule ~5 min
Inherited codebase, no documentation
React + Node project. No docs, sparse commits, nobody to ask. You don't know what kinds of changes this codebase needs.
Populator scans 300 commits. Finds: 40% touch API + DB together, 25% are CSS fixes, 15% are config changes. Discovers 5 natures.
schedule ~5 min
Realistic expectation: A sparse codebase produces a thinner taxonomy than a well-documented one. As you work and accumulate gotchas, re-run the populator to deepen it.
schedule Time expectations by project size
| Project | Populator | Identifier | Executor (per step) |
|---|---|---|---|
| Small (5-20 files, no git) | 1-2 min | 30 sec | 2-5 min |
| Medium (50-200 files, git) | 3-5 min | 1-2 min | 3-10 min |
| Large (500+ files, monorepo) | 5-10 min | 2-3 min | 5-15 min |
Times include QnA interaction. Actual time depends on Claude model, file sizes, and how many questions you answer.
The three layers, in detail
radar Layer 1 Populator
Scans your project's artifacts and discovers the change types that have actually occurred.
search What it scans
| Source | Reveals |
|---|---|
| history Git history | Commit patterns, file groups, reverts |
| menu_book Learnings docs | Gotchas, traps, domain rules |
| memory Memory files | Past decisions, known issues |
| extension Existing skills | Formalized workflows to link |
| settings Config files | Tech stack, dependencies |
| trending_up File patterns | Most-changed files = complexity |
| bug_report Tests | Expected change types |
| compare Before/after pairs | Direct transformation evidence |
park Hierarchical taxonomy output
Category: Styling
CSS Restoration - inject missing stylesheets
Responsive Adaptation - override desktop CSS for mobile
Asset Embedding - replace broken refs with inline
Category: Behavior
Interactive Enhancement - add JS handlers, chart init
Data Hydration - populate empty containers
Category: Structure
Surgical Addition - add new blocks, touch nothing
Excision - remove unwanted elementsinfo Example from an HTML project. A Python API project discovers entirely different natures.
category Layer 2 Identifier
Classifies your request, determines blast radius, writes an execution plan. Does not execute.
Signal matching
Parses keywords, matches against the decision tree — first category, then sub-nature.
Scope detection
File (1), module (2-10), or project (10+). Each tier uses different map types.
QnA intelligence
Diagnostic questions when ambiguous. Max 2 rounds. Detects state contradictions.
Compound detection
Multiple natures? Presents the breakdown and execution order. You confirm first.
build Layer 3 Executor
One prompt per nature, same four-phase template. Generated by the populator, refined by field guides.
Phase 1: Audit
Read the semantic map. Inventory tech stack, patterns, landmarks.
Phase 2: Discover
Find assets and dependencies. Check project first, ask user if missing.
Phase 3: Implement
Execute following constraints. Read field guide. Plan minimal diff first.
Phase 4: Verify
Structural check, scope check, no collateral damage. Update map.
What the output actually looks like
Real examples of the files the framework produces.
description nature-taxonomy.md
# Nature-of-Change Taxonomy
<!-- Project: my-dashboard -->
<!-- Generated: 2026-04-15 -->
<!-- Natures: 7 (3 categories) -->
## Category: Styling
### CSS Restoration
- Definition: Inject missing stylesheets to restore visual rendering
- Signals: "unstyled", "CSS missing", "page looks broken"
- Risk: MEDIUM — wrong chunk order silently breaks navbar
- Executor: fix-tarana-ui.md
- Field guide: none
### Responsive Adaptation
- Definition: Override desktop CSS for mobile/tablet viewports
- Signals: "mobile", "responsive", "breakpoint"
- Risk: HIGH — specificity cascade corruption
- Executor: responsive-adaptation.md
- Field guide: MOBILE_CSS_LEARNINGS.md
## Decision Tree
1. page unstyled / CSS missing → CSS Restoration
2. mobile / responsive / tablet → Responsive Adaptation
3. remove / delete / strip → Excision
...map semantic-map (file-level)
# Semantic Map: dashboard.html
<!-- Source: /project/pages/dashboard.html -->
<!-- File size: 1,903,211 bytes -->
<!-- content-hash: a3f8b2c1e9 -->
## Tech Stack
- CSS: modern-normalize, MUI v5 (css-* hashes)
- JS: Highcharts v12.1.2 (embedded, non-functional)
- Fonts: Lato (Google), Montserrat (@font-face)
## Design Tokens
- Primary: #0367a9 Text: #1f2937
- Good: #16a34a Warn: #d97706 Bad: #dc2626
- Font body: 14px/1.5 Lato, sans-serif
- Spacing: 8px base, 14px card padding
## Structure
- Empty containers: #bn-trend-chart, #rn-trend-chart,
#dl-throughput-chart, #ul-throughput-chart
- Injected overlay: .tcs-sidebar (lines 6-37)
- Toggle buttons: .MuiToggleButton-root (7 buttons)public Global registry (~/.claude/nature-library/registry.md)
# Nature Library
<!-- 12 natures across 3 projects -->
Nature Category Risk Projects
Surgical Addition Enhancement LOW 3 projects
CSS Restoration Restoration MED 1 project
Responsive Adaptation Adaptation HIGH 2 projects
Schema Migration Correction MED 1 project
Interactive Enhancement Enhancement MED 2 projects
...What a QnA conversation looks like
The identifier asks diagnostic questions when your request is ambiguous. Here's a real conversation flow.
Identifier QnA — ambiguous request
(1) Visual appearance / page looks unstyled
(2) Layout breaks on mobile or tablet
(3) Charts or data sections are empty
(4) Clicking buttons or tabs does nothing
(5) Something else — describe it
1. Data Hydration — initialize the empty chart containers
2. Responsive Adaptation — override desktop layout for mobile
I'd execute them in that order (charts first, then responsive overrides). Does this match, or is it actually just one of these?
CLASSIFICATION:
Natures: Data Hydration + Responsive Adaptation
Scope: file-level (dashboard.html)
Risk: HIGH (responsive has specificity traps)
Run:
/data-hydration first, then /responsive-adaptationPopulator QnA — sparse project
Coverage: 2/7 — I need more context.
What kind of project is this? What's the end goal?
(1) Static HTML pages needing offline rendering
(2) Backend API / service
(3) Frontend web app
(4) Infrastructure / config
(5) Something else
(1) Fixing broken styling / injecting CSS
(2) Making pages work on mobile
(3) Adding interactivity (charts, toggles)
(4) Removing injected overlays
(5) Embedding fonts/images for offline
Select multiple with commas
Semantic maps — cached intelligence
Persistent file audits. All three layers read and write them.
File map
1 file. Tech stack, tokens, structure, dependencies. Content hash + snapshot.
Module map
Directory. File roles, inter-dependencies, shared patterns.
Dependency graph
Project-level. Which files depend on which. Blast radius detection.
autorenew Diff-based freshness
tag Hash check
Match → map is fresh. Mismatch → compute diff.
difference Partial re-audit
Only re-audit sections affected by the diff.
sync Update
Refresh hash + snapshot. Full re-audit only when >40% changed.
hard_drive File sizes & disk footprint
| File | Typical size | Count per project |
|---|---|---|
nature-taxonomy.md | 2-8 KB | 1 |
| File semantic map | 1-3 KB each | 5-20 (key files only) |
| Module map | 1-2 KB each | 2-5 |
| Dependency graph | 1-4 KB | 1 |
| Executor prompt | 3-6 KB each | 5-10 |
| Total footprint | 50-150 KB — add semantic-maps/ to .gitignore if you prefer | |
Evolution — natures grow with you
Global library stores reusable natures across projects. Re-runs diff and propose changes.
~/.claude/nature-library/ ← GLOBAL (shared)
registry.md ← browsable index
executors/ ← reusable prompts
Project A/ ← LOCAL
nature-taxonomy.md ← inherits global + local
Project B/ ← LOCAL
nature-taxonomy.md ← same global, different localNew natures
Global (reusable) or local (project-specific)? You choose.
Updates
New gotchas and signals from recent work. Executor + field guide updated.
Merges
80%+ overlap. Combined into one nature.
Splits
Divergent constraints. Split into focused sub-natures.
Promotion: Local nature in 2+ projects → populator suggests promoting to global.
Requirements & compatibility
What you need to run the framework.
Claude model
Recommended: Claude Opus 4 or later (best for populator — complex discovery + generation). Works with: Sonnet 4 for identifier + executor tasks. Not recommended: Haiku (too shallow for populator clustering).
Claude Code environment
Works in CLI, VS Code extension, JetBrains extension, and web app. No MCP servers required. No hooks. No special permissions. Purely prompt-based.
Project prerequisites
None. Works on any project with source files. Git recommended but not required. Learnings docs improve quality but aren't needed. The QnA fills gaps.
Context window
Taxonomy + semantic map fit easily in context (~5-10 KB). Large executor prompts (6 KB each) may matter on smaller context models. Use Opus for best results.
Framework vs. CLAUDE.md
You might already have a CLAUDE.md with project conventions. When should you use which?
| CLAUDE.md | Nature of Change Framework | |
|---|---|---|
| What it is | Static instructions file | Dynamic discovery + classification system |
| Who writes it | You, manually | Populator generates from project evidence |
| Scope | General project rules | Per-change-type methodology with constraints |
| Compound changes | No ordering or handoffs | Execution plans with step-by-step context |
| Evolves | When you remember to edit it | Populator re-run discovers new patterns |
| Cross-project | Copy-paste | Global library with automatic promotion |
| Best for | Coding style, naming conventions, "always do X" | Complex changes, risk management, recurring patterns |
They're complementary. Keep your CLAUDE.md for coding style rules. Use the framework for change methodology. The populator even reads your CLAUDE.md as a signal source.
Troubleshooting — when things go wrong
warning Populator discovers zero natures
The project has no transformation evidence — no git history, no modified files, no learnings. Fix: Answer the QnA questions with specific examples. Or just start working, and re-run the populator after a few days of changes.
shuffle Identifier misclassifies the nature
The taxonomy's decision tree has wrong signal keywords. Fix: Edit nature-taxonomy.md directly — update the Signals field for the mismatched nature. Or tell the identifier "actually this is [correct nature]" and it will route correctly.
broken_image Executor breaks the file
The executor's methodology doesn't account for a project-specific gotcha. Fix: Undo with git checkout or the backup (executors create backups for HIGH-risk natures). Then edit the executor prompt to add the missing constraint. Consider adding a learnings doc so the populator captures it on re-run.
edit_document I edited an executor — will the populator overwrite it?
No. The populator never overwrites existing executor prompts. On re-run, it will propose updates (new gotchas, signals) which you can accept or reject. Your manual edits are always preserved.
folder_delete Too many framework files cluttering my project
Add semantic-maps/ and execution-plan.md to .gitignore. Keep nature-taxonomy.md and executor prompts in version control (they're useful for the team). Total footprint is typically 50-150 KB.
psychology The taxonomy feels wrong but I can't articulate why
Re-run the populator with the diff+propose mode. It will show what it found and let you merge, split, or rename natures. You can also just edit nature-taxonomy.md directly — it's a markdown file you own.
Common questions
language Is this only for HTML projects?
layers Do I have to use all three layers?
bolt What about quick one-line changes?
share Can I share natures across projects?
~/.claude/nature-library/. Natures in 2+ projects get promoted to global.error What if the clustering is wrong?
Getting started
Two prompt files. Two minutes to set up. No dependencies.
file_copy Create the prompt files
Create nature-populator.md and nature-identifier.md in your project root. These are the full prompt texts that Claude reads when you invoke each layer. Alternatively, place them in .claude/commands/ for slash-command access (/nature-populator, /nature-identifier).
play_arrow Run the populator
Tell Claude: "run the nature populator on this project." It scans your files, asks questions about gaps, and produces the taxonomy + semantic maps + executor prompts.
rate_review Review outputs
Read nature-taxonomy.md. Check the natures make sense. Edit generated executors if needed — they're your files, the populator never overwrites them.
task_alt Use per task
"Identify the nature of change: [your request]." The identifier classifies, plans, and tells you which executor to run.
That's it. No config files, no dependencies, no MCP servers. Just two markdown prompts and the knowledge already in your codebase. The framework bootstraps itself from your project's own history.
download Getting the prompt files
The prompt files are plain markdown — no special format, no compilation. You can: