intent-archaeology
Reconstructs WHY code exists the way it does: mines git history (log -follow, blame, ticket references) for a file or symbol, then has the LLM rebuild the intent story with commit-level evidence and c
SKILL.mdskills/quality/intent-archaeology/SKILL.md
GitHub/intent
Reconstructs the intent story of a file (or a symbol within it) from git history, blame and ticket references - with commit evidence instead of guesses.
What this is for
- Understand foreign or your own old code before touching it: why is it built this way, why does this workaround exist, what discussion led to a strange condition?
- Replaces 2-4 hours of manual git archaeology with one invocation and commit evidence in minutes.
- Read-only skill. Analyzes one file or symbol (function/class) per run, no directory trees in one go, no access to external ticket systems (only extract IDs and list them).
PROTECTION RULE - never ~/.claude/
Read-only skill. Guard required if write mode added later.
What You Must Do When Invoked
If /intent -help or /intent -h (without further arguments) is invoked: output
the ## Usage section unchanged and stop.
Otherwise follow these steps in order, skipping none.
Step 1 - Help check
If invoked with -help or -h, output the ## Usage section unchanged and stop.
Step 2 - Clarify target
Clarify: -ProjectDir (repo root or a subfolder), -File
(repo-relative to -ProjectDir), optional -Symbol (function/class name). If
something is missing, ask the user. Show what was detected, then:
ProjectDir: <path>
File: <file>
Symbol: <symbol or "none">
Continue? (yes/no)
Only continue after confirmation.
Step 3 - Collect evidence
& "<SKILL_DIR>/scripts/git-mine.ps1" -ProjectDir "<path>" -File "<file>" [-Symbol "<symbol>"]
Read JSON output. If script aborts with Exit-Code != 0 (no git repo, path
missing, file missing): show the Write-Error message to the user, stop.
Step 4 - Analysis
With the JSON from Step 2:
- Read commits chronologically (the script delivers them oldest-first), form phases (creation, refactors, fixes, workarounds).
- Per phase reconstruct the intent: What was attempted? What triggered it (ticket ID, bugfix wording, revert)?
- Explicitly handle anomalies: reverts, quick follow-up fixes (< 2 days after the previous change), commits with "hack", "workaround", "temp", "fix fix", etc.
- If
symbolis set butsymbolLogAvailable: false: note this in the report, analysis falls back to file level. - Each statement gets a confidence level (
proven/likely/suspected) according to the confidence level guidelines.suspectedstatements belong exclusively in the "Open questions" section, never among the proven findings.
Step 5 - Write report
Report structure (Markdown):
- Summary (max 5 sentences) - the why story in brief.
- Chronology - per phase: time period, reconstructed intent, evidence (commit hashes), confidence level.
- Warnings - workarounds/provisionals that were never cleaned up, with evidence.
- Open questions - all
suspectedclassifications, plus ticket IDs fromticketIdsthat would need to be looked up to close gaps.
Save the report as intent-report-<filename>.md in the current
working directory (not into the analyzed repo).
Step 6 - Summarize
Tell the user the path of the written report and summarize the core findings (2-3 sentences) directly in chat.
Usage
/intent # interactive: ask for repo, file, optional symbol
/intent <repo> <file> # file analysis
/intent <repo> <file> <symbol> # symbol analysis
/intent -help # show usage, stop