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.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:

  1. Read commits chronologically (the script delivers them oldest-first), form phases (creation, refactors, fixes, workarounds).
  2. Per phase reconstruct the intent: What was attempted? What triggered it (ticket ID, bugfix wording, revert)?
  3. Explicitly handle anomalies: reverts, quick follow-up fixes (< 2 days after the previous change), commits with "hack", "workaround", "temp", "fix fix", etc.
  4. If symbol is set but symbolLogAvailable: false: note this in the report, analysis falls back to file level.
  5. Each statement gets a confidence level (proven / likely / suspected) according to the confidence level guidelines. suspected statements belong exclusively in the "Open questions" section, never among the proven findings.

Step 5 - Write report

Report structure (Markdown):

  1. Summary (max 5 sentences) - the why story in brief.
  2. Chronology - per phase: time period, reconstructed intent, evidence (commit hashes), confidence level.
  3. Warnings - workarounds/provisionals that were never cleaned up, with evidence.
  4. Open questions - all suspected classifications, plus ticket IDs from ticketIds that 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