decision-archaeology

ntsk's avatarfrom ntsk

Investigate why code was written a certain way. Use when tracing decision history through git blame, commit logs, PRs, and issues to understand the reasoning behind code changes.

⭐3stars🔀2forks📁View on GitHub🕐Updated Jan 4, 2026

When & Why to Use This Skill

The Decision Archaeology skill empowers developers to uncover the 'why' behind any line of code by automatically tracing its history through git blame, commit logs, and GitHub Pull Requests. By synthesizing context from historical discussions and issue trackers, it transforms legacy code investigation into a streamlined, automated workflow, helping teams understand technical debt and architectural decisions without manual searching.

Use Cases

  • Legacy Code Onboarding: Quickly understand the reasoning behind complex logic in an unfamiliar codebase by tracing it back to the original PR and design discussion.
  • Contextual Bug Analysis: Investigate whether a specific line of code was a deliberate fix for a past edge case or an accidental side effect of a previous change to avoid regressions.
  • Refactoring Safety: Before modifying critical code, use this skill to ensure you understand the original constraints and requirements documented in historical issues and commit messages.
  • Technical Debt Audit: Evaluate the history of a module to determine if past decisions are still valid or if they were temporary workarounds that now require a proper architectural fix.
namedecision-archaeology
descriptionInvestigate why code was written a certain way. Use when tracing decision history through git blame, commit logs, PRs, and issues to understand the reasoning behind code changes.
- Bash(git log*)
- Bash(git show*)
- Bash(git blame*)
- Bash(git diff*)
- Bash(gh pr list*)
- Bash(gh pr view*)
- Bash(gh issue list*)
- Bash(gh issue view*)
- Bash(gh search*)
- Bash(gh api*)

Decision Archaeology Skill

Rules

Read-only operations only. For gh api: GET requests only. No -X POST/PUT/PATCH/DELETE or -f/-F flags.

Workflow

  1. Identify code - Target file, lines, or function
  2. Find commit - git blame → introducing commit
  3. Trace PR/Issue - Check commit message for #123 references
  4. Summarize rationale - Output findings

For detailed commands: See references/commands.md

Key Commands

git blame -L <start>,<end> <file>    # Find who changed lines
git log -S "code" --oneline          # Find when code was added
gh pr list --search "<sha>" --state all  # Find PR for commit

Output Format

## Decision Archaeology Report

### Target
- File: [path/to/file]
- Lines: [XX-YY]

### Timeline

#### [Date] Commit: [short-sha]
- Author: [name]
- Message: [commit message]
- PR: #[number] [title]
- Related Issue: #[number]

### Decision Rationale
[Summary of why, based on PR discussions, issue context, commit messages]

### Key References
- PR #[number]: [URL]
- Issue #[number]: [URL]
- Commit: [sha]

Tips

  • Start with git blame to find introducing commit
  • Check commit message for #123 references
  • PR descriptions and review comments contain the "why"