rjmurillo Chesterton's Fence Investigation
Enforce epistemic humility before changing existing systems. Understand original purpose before proposing changes.
Quick Start
# Investigate why code exists before changing it
/chestertons-fence "path/to/file.py" "remove unused validation"
# Investigate an ADR before deprecating it
/chestertons-fence "docs/architecture/ADR-005.md" "allow bash scripts"
Triggers
| Phrase | Context |
|---|---|
why does this exist |
Investigating existing code or patterns |
chestertons fence |
Explicit investigation request |
before removing |
Planning deletion or replacement |
investigate history |
Researching original rationale |
prior art investigation |
ADR-required investigation |
Quick Reference
| Input | Output | Destination |
|---|---|---|
| File path or ADR number | Investigation report | .agents/analysis/NNN-chestertons-fence-TOPIC.md |
| Component description | Historical context summary | stdout (JSON) |
When to Use
Use this skill BEFORE proposing changes to existing:
- Code patterns or architectural decisions
- ADRs, constraints, or protocol rules
- Workflow configurations or CI pipelines
- Skills, hooks, or agent prompts
Process
1. Identify Structure What exists? Where is it defined?
|
v
2. Git Archaeology git log, git blame to find origin commit
|
v
3. PR/ADR Search Find the PR or ADR with original rationale
|
v
4. Dependency Analysis What references or depends on this?
|
v
5. Generate Report Fill the investigation template
|
v
6. Decision REMOVE | MODIFY | PRESERVE | REPLACE
Step Details
Step 1: Identify Structure. Locate the exact file, function, pattern, or constraint under investigation. Record its current form.
Step 2: Git Archaeology. Run git log --follow and git blame on the target. Identify the commit that introduced it, the author, and the date.
Step 3: PR/ADR Search. Search for the originating PR using gh pr list --search. Check .agents/architecture/ for related ADRs. Look for comments explaining intent.
Step 4: Dependency Analysis. Use grep or Grep tool to find all references. Map upstream and downstream dependencies. Identify what breaks if the structure is removed.
Step 5: Generate Report. Use the template at the bundled templates/chestertons-fence-investigation.md in this skill directory. Fill all sections with evidence from steps 1 through 4.
Step 6: Decision. Based on evidence, recommend one action:
| Decision | When to Use |
|---|---|
| PRESERVE | Original rationale still applies |
| MODIFY | Purpose valid but implementation needs updating |
| REPLACE | Better approach exists, original concern addressed |
| REMOVE | Original rationale no longer applies, with evidence |
Usage
# Investigate a file or pattern
python3 scripts/investigate.py --target path/to/file.py --change "remove unused validation"
# Investigate an ADR
python3 scripts/investigate.py --target docs/architecture/ADR-005.md --change "allow bash scripts"
# Output as JSON (for automation)
python3 scripts/investigate.py --target path/to/file.py --change "description" --format json
Scripts
| Script | Purpose | Exit codes |
|---|---|---|
scripts/investigate.py |
Git archaeology (origin commit, recent changes), related-ADR search, and dependent search for a target; emits a Markdown or JSON investigation report from the bundled template. | 0=success, 1=error |
Integration with Agent Workflows
| Agent | How to Integrate |
|---|---|
| Analyst | Run this skill first when investigating changes. The report is a prerequisite for any change proposal. |
| Architect | ADRs that deprecate or replace existing patterns MUST include a "Prior Art Investigation" section. Use this skill to generate it. |
| Implementer | Before implementing deletions or major refactoring, verify an investigation report exists. If missing, route to analyst. |
| Critic | When validating plans that remove or replace existing systems, check for investigation evidence. Auto-reject proposals without historical context. |
Anti-Patterns
| Avoid | Why | Instead |
|---|---|---|
| Removing code you do not understand | May break hidden invariants | Investigate first, then decide |
| Assuming dead code is unused | Hyrum's Law: someone depends on it | Run dependency analysis |
| Skipping PR/ADR search | Loses original design rationale | Always check git history and PRs |
| Proposing replacement without evidence | Cannot compare tradeoffs | Document original constraints first |
Verification
- Investigation ran for the target before any change proposal was made.
- Origin commit, recent changes, related ADRs, and dependents were gathered (or explicitly recorded as none found).
- The resulting report (template-based or inline fallback) is attached to the change proposal or the ADR Prior Art Investigation section.
Template
Investigation reports use the template at the bundled templates/chestertons-fence-investigation.md in this skill directory.
References
| File | Content |
|---|---|
references/chestertons-fence-mental-model.md |
Core mental model, principle, investigation checklist, related models |
references/boy-scout-rule.md |
Scoped improvement boundaries, connection to investigation workflow |
references/legacy-code-techniques.md |
Bottom-up refactoring approach, inheritance vs composition, reading list |