context-legacy

Context Legacy Skill

Multi-phase discovery for legacy code. Reads code, git, and optionally Jira to reconstruct intent. Never modifies source files. All output goes to memory/discoveries/ and docs/.

Phases

Phase 0 → Memory query          (check what's already indexed — avoid redoing work)
Phase 1 → Code archaeology      (static analysis — always)
Phase 2 → Git history           (always)
Phase 3 → Jira enrichment       (only if JIRA_* env vars present in .env)
Phase 4 → Cross-reference       (synthesize all signals)
Phase 5 → Output generation     (notes + candidates + re-index)

---

Phase 0 — Memory query

Before reading any code, check if the module was already discovered.

memory/.venv/bin/python -m memory.query "<module_name>" 2>/dev/null | head -30

If results show prior discovery notes for this module:

• Read memory/discoveries/<module-slug>-survey.md if it exists
• Note what's already known — skip re-deriving it in Phases 1–2
• Focus new work on gaps or on Jira context not yet captured

If no prior results, proceed to Phase 1 fresh.

---

Phase 1 — Code archaeology

Goal: understand what the module does, not how it works.

# Map the target
find <module_path> -type f | sort
wc -l <module_path>/**/* 2>/dev/null | sort -rn | head -20

# Hot files: most commits in last 2 years
git log --since="2 years ago" --pretty=format: --name-only -- <module_path> \
  | sort | uniq -c | sort -rn | head -10

# Cold files: untouched 3+ years, still present
git log --before="3 years ago" --name-only --pretty=format: -- <module_path> \
  | sort -u > /tmp/cold-all.txt
git log --since="3 years ago" --name-only --pretty=format: -- <module_path> \
  | sort -u > /tmp/cold-recent.txt
comm -23 /tmp/cold-all.txt /tmp/cold-recent.txt

Read hot and cold files first. For each, note:

• Public interface (classes, functions exported, iface.hh for C++)
• Non-obvious dependencies (#include, imports, deps file)
• Surprising patterns — magic numbers, global state, platform ifdefs
• Existing comments that hint WHY (not what)
• Markers already present (:HACK:, :UNSAFE:, TODO, FIXME, XXX)