legacy-codebase-navigation
Navigate, understand, and debug large legacy codebases (Rails, Django, early Node). Techniques for tracing data through deep helper chains, reading mutation-heavy code without getting lost, and finding the exact transformation that damaged your data.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- legacy-codebase-navigation
- author
- Steadfaste Fleet (troubleshooter)
- license
- MIT
- version
- 1.0.0
- metadata
- { "hermes": { "tags": [ "legacy", "rails", "debugging", "codebase-navigation", "data-tracing" ], "related_skills": [ "root-cause-debugging", "project-map", "codebase-design" ] } }
- platforms
- [ "macos", "linux" ]
- description
- Navigate, understand, and debug large legacy codebases (Rails, Django, early Node). Techniques for tracing data through deep helper chains, reading mutation-heavy code without getting lost, and finding the exact transformation that damaged your data.
03 SKILL.md 正文
Legacy Codebase Navigation
Overview
Legacy codebases share common traits that make them harder to debug than greenfield projects:
- Deep helper chains — data passes through 5+ transformation layers (controller → helper → sub-helper → sub-sub-helper)
- Mutation-heavy code —
gsub!,gsub,strip,upcasechained in long sequences, each step mutating state - Side-effect rich — functions set instance variables, write logs, touch the DB as a side effect of "computation"
Tracing Data Through Helper Chains
1. Build the call graph first
Find every link in the chain before touching code:
# In Rails: find the helper method and all its callers
grep -rn "def my_helper" app/helpers/
grep -rn "my_helper(" app/ --include="*.rb" | grep -v "def "
# In any codebase: who calls this method?
grep -rn "method_name(" . --include="*.rb" --include="*.py" --include="*.js" | grep -v "def "
2. Trace the data, not the code
Follow the value through each transformation. For each link in the chain, write down: input → output. When the output is wrong, the transformation that changed it is the bug.
# Instead of reading this chain linearly:
title.gsub('(', ' - ').gsub(')', '').strip.upcase
# Ask: what does EACH step do to the value?
# 1. gsub('(', ' - ') → "Artist (INST.)" → "Artist - INST.)"
# 2. gsub(')', '') → "Artist - INST."
# 3. strip → "Artist - INST."
# 4. upcase → "ARTIST - INST."
3. Use the debugger at the boundary
Set a breakpoint at the entry and exit of the suspect helper — not inside every line:
# Rails: binding.pry at the helper entry, print the input
# then step through only if the output looks wrong
Reading Mutation-Heavy Code Without Getting Lost
- Make a state table — list every variable and its value at each step. Mutation chains are just state tables with the intermediate values hidden.
- Distinguish computation from side effects — a method that mutates an instance variable AND returns a value is doing two things; you must check both.
- Look for the "last writer wins" pattern — in long chains, the final mutation determines the result; earlier ones may be dead code or bugs.
Finding the Exact Transformation That Damaged Data
When you know data is corrupted but not where:
- Identify the shape of the damage — what does the bad data look like vs the good data? (Missing suffix? Wrong case? Duplicated text?)
- Search for transformations that could produce it:
grep -rn "gsub\|sub(\|strip\|upcase\|downcase\|tr(" app/helpers/ app/models/ | head -50 - Reproduce with the actual data — feed a known-good sample through each candidate transformation in a console/REPL and compare outputs.
- Confirm with the DB — find rows that match the damage pattern and rows that don't; the transformation must explain the difference.
Pitfalls
- ❌ Reading linearly — helper chains are trees, not lists. Trace values.
- ❌ Fixing the symptom — the wrong output is produced 4 layers up; patching the display hides it. Fix the transformation.
- ❌ Trusting method names —
clean_titlemay not clean anything. Read the body. - ❌ Ignoring side effects — a "pure" helper that writes to the DB is
anything but. Check for
update,save,createin helpers.
Related
root-cause-debugging— the 6-phase debugging frameworkproject-map— structural project analysiscodebase-design— module vocabularyrails-data-pipeline-debugging— specific data-pipeline patterns in Rails
04 同仓库更多 Skills
macbook-linux-maintenance
Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.
governance-regression-triage
Triage a host's governance issues: what changed.
enforcement-immutability
Use when enforcement files lose their immutable flag.
steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
steadfaste-fleet-maintenance
Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.
fleet-preflight
DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its "Repo-Specific Pre-Flight" section covers git search, Hermes boundary, and deployment verification.