chestertons-fence

name	chestertons-fence
version	1.1.0
description	Investigate historical context of existing code, patterns, or constraints before proposing changes. Automates git archaeology, PR/ADR search, and dependency analysis to prevent removing structures without understanding their purpose. Use when you ask "why does this code/constraint exist", "is it safe to remove this". Do NOT use for forward-risk analysis (use pre-mortem).
license	MIT
user-invocable	true

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