# Repo Archaeologist

> Use when setting up a new repo for TKS team, onboarding a legacy project, or when institutional knowledge is missing/outdated. Triggers: 'document this repo', 'new project setup', 'knowledge extraction', 'what does this codebase do', missing DOMAIN_MAP.md or TRAPS.md or DECISIONS_LOG.md in docs/institutional-memory/.

- Skill: `mduongvandinh/repo-archaeologist` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mduongvandinh/repo-archaeologist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mduongvandinh/repo-archaeologist/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mduongvandinh (https://skillmd.com/u/mduongvandinh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mduongvandinh/repo-archaeologist

---


# Repo Archaeologist

## Overview

Extract institutional knowledge from a codebase that only exists in people's heads or scattered across git history. Output 3 living documents that protect against 属人化 (knowledge trapped in individuals).

**Core principle**: Read code + git history + bug tickets → generate knowledge docs → dev reviews in 5 minutes. Dev never writes documentation from scratch.

## When to Use

- New repo joining TKS portfolio
- Legacy repo with no documentation
- Quarterly refresh of existing docs
- Before a key developer rotates off project
- **NOT** for: routine PR documentation (use `/knowledge-capture` instead)

## Prerequisites

- GitHub CLI (`gh`) authenticated
- ClickUp API access (optional, enriches output)
- Repo cloned locally with full git history

## Process

### Phase 1: Gather Raw Data

First, detect project type and set variables:

```bash
# Auto-detect source root and build tool
if [ -d "src/main/java" ]; then
  SRC_ROOT="src/main/java"
  TEST_ROOT="src/test/java"
  FILE_EXT="*.java"
elif [ -d "src" ]; then
  SRC_ROOT="src"
  TEST_ROOT="src"
  FILE_EXT="*.ts"
else
  SRC_ROOT="."
  TEST_ROOT="."
  FILE_EXT="*.py"
fi

# Auto-detect build tool
if [ -f "build.gradle" ] || [ -f "build.gradle.kts" ]; then
  BUILD_TOOL="gradle"
elif [ -f "pom.xml" ]; then
  BUILD_TOOL="maven"
elif [ -f "package.json" ]; then
  BUILD_TOOL="npm"
else
  BUILD_TOOL="unknown"
fi

# Use OS-appropriate temp dir
TMPDIR="${TMPDIR:-/tmp}"
```

Then gather data:

```bash
# 1. PR history with descriptions (decisions live here)
gh pr list --state merged --json number,title,body,mergedAt,author,files \
  --limit 500 --jq '.[] | select(.body | length > 50)' > "$TMPDIR/pr-history.json"

# 2. Code churn — who touched what, how often
git log --numstat --since="12 months ago" --format="COMMIT:%H|%ae|%aI|%s" \
  > "$TMPDIR/git-churn.txt"

# 3. Bug-related commits (--grep flags are OR by default with --all)
#    Use separate commands to ensure OR logic, then deduplicate
{ git log --all --oneline --grep="fix" --since="12 months ago"; \
  git log --all --oneline --grep="bug" --since="12 months ago"; \
  git log --all --oneline --grep="hotfix" --since="12 months ago"; \
} | sort -u > "$TMPDIR/bug-commits.txt"

# 4. Code comments containing warnings — use auto-detected SRC_ROOT
grep -rn "FIXME\|HACK\|WORKAROUND\|DO NOT\|注意\|TODO.*careful\|WARNING" \
  --include="$FILE_EXT" "$SRC_ROOT" > "$TMPDIR/warning-comments.txt" 2>/dev/null || true

# 5. Config files for environment context (search both .yml and .properties)
find . \( -name "application*.yml" -o -name "application*.properties" \
  -o -name "application*.yaml" -o -name ".env*" -o -name ".env.example" \
  -o -name "docker-compose*" -o -name "Dockerfile" \) \
  -not -path "*/build/*" -not -path "*/node_modules/*" \
  | head -20 > "$TMPDIR/config-files.txt"
```

**Note on ClickUp**: ClickUp integration is OPTIONAL. If no ClickUp API token is available, skip bug history from ClickUp and rely solely on git history (step 3 above). The skill MUST work without ClickUp — git history alone provides sufficient data for a useful output.

### Phase 2: Generate Documents

Create `docs/institutional-memory/` directory. Generate 3 files:

#### File 1: DECISIONS_LOG.md

**What to extract from PRs**:
- Filter PRs where body contains: "because", "instead of", "trade-off", "decided", "chosen", "なぜ", "理由", "選定"
- Classify each: Architecture Decision | Business Rule Change | Performance Optimization | Bug Root Cause
- For each decision: WHEN (date) → WHO (author) → WHAT (change) → WHY (reasoning) → IMPACT (what breaks if reversed)

**Structure**:
```markdown
# Decision Log — [Project Name]
Auto-generated by /repo-archaeologist | Last scan: [date]
Repo: [repo-url] | PRs analyzed: [count] | Period: [date range]

## How to use this file
- Before making architectural changes: search here first
- Before reverting old code: check if there's a decision explaining WHY
- After making new decisions: /knowledge-capture will auto-update this file

## Architecture Decisions
### DEC-001: [Short title]
- **When**: [date] (PR #[number], by @[author])
- **Context**: [Why this decision was needed — business driver]
- **Choice**: [What was chosen]
- **Alternatives considered**: [What was rejected and why]
- **Constraint**: [External constraint if any — client requirement, legacy system, regulation]
- **⚠️ Reversal risk**: [What breaks if someone changes this without understanding context]
```

**Critical rule**: Every decision MUST have "Reversal risk". This is the most valuable field — it's what prevents the next developer from breaking things.

#### File 2: DOMAIN_MAP.md

**What to extract from code**:
- Package/module structure → business domain mapping
- Database migration files → domain model understanding
- Scheduled jobs/batch configs → operational context
- API endpoints → user-facing functionality
- External service integrations → dependency awareness

**Structure**:
```markdown
# Business Domain Map — [Project Name]
Read this BEFORE reading any code.

## Client Profile
- Company: [name], Industry: [industry]
- End users: [who uses the system and why]
- Peak seasons: [when workload spikes — CRITICAL for deploy planning]
- Escalation pattern: [what makes client call/email urgently]

## Module Map
### `[module-name]/` — [Business meaning in Vietnamese]
- **Japanese term**: [日本語の業務用語]
- **What it does for the business**: [2-3 sentences, no code jargon]
- **Trigger**: [What causes this module to run — user action, schedule, event]
- **If it fails**: [Business impact + escalation level: 低/中/高]
- **Key files**: [3-5 most important files]
- **Domain expert on team**: [@person] (backup: [@person])
- **Connected to**: [Other modules that depend on or feed into this]

## Data Flow
[Describe how data moves through the system in business terms]
Example: "Client's customer uploads CSV → system validates → calculates tax → 
generates 請求書 → sends to client for approval → client sends to their customer"

## External Dependencies
| System | Purpose | Owner | SLA | Risk if down |
|--------|---------|-------|-----|-------------|
```

**Critical rule**: Write in Vietnamese for team, keep Japanese business terms (日本語) as-is. A dev who reads this file should understand the BUSINESS before touching code.

#### File 3: TRAPS.md

**What to scan for**:

| Trap Category | Detection Method |
|--------------|-----------------|
| Timezone | Search for `LocalDateTime.now()`, `new Date()`, `datetime.now()` without timezone |
| Rounding | Search for `BigDecimal`, `Math.round`, `toFixed` near money/tax logic |
| Encoding | Search for charset, encoding, Shift-JIS, Windows-31J, CSV export |
| Hardcoded config | Search for hardcoded URLs, IPs, magic numbers in business logic |
| External API quirks | Search for `Thread.sleep`, retry logic, rate limit comments |
| Date edge cases | Search for month-end, fiscal year, leap year logic |
| Multi-tenant leaks | Search for missing tenant filters in queries |

**Also extract from**:
- Bug commits that took > 1 day to resolve (git log + ClickUp cross-reference if available)
- Code comments with WARNING/FIXME/HACK/注意
- Files with > 5 hotfixes in same area (git blame analysis)
- Dependency health (based on auto-detected build tool):
  - Gradle: `./gradlew dependencyUpdates` (if plugin available) or read `build.gradle`
  - Maven: `mvn versions:display-dependency-updates`
  - npm: `npm outdated`
  - If dependency check command unavailable, skip — this is optional enrichment

**Structure**:
```markdown
# ⚠️ Trap Map — [Project Name]
READ THIS BEFORE WRITING CODE. Every trap here caused a real bug.

## 🔴 Critical Traps (Mistake = production bug)
### TRAP-001: [Short name]
- **Files**: [Exact file paths]
- **Wrong way**: [Code that looks right but is wrong]
- **Right way**: [Correct code with explanation]
- **Why it's a trap**: [Why the wrong way seems reasonable]
- **History**: [Bug ticket or incident that revealed this trap]
- **Detection**: [How to catch this in code review]

## 🟡 Caution Traps (Mistake = wasted time)
[Same structure, lower severity]

## 🟢 Known Workarounds (Ugly but necessary)
[Document workarounds that look like bugs but are intentional]
```

**Critical rule**: Every trap MUST have "Wrong way" and "Right way" as actual code. Abstract descriptions are useless — show the exact code pattern.

### Phase 3: Validate

After generating all 3 files:

1. Run `wc -l` on each file — DOMAIN_MAP should be longest, TRAPS shortest
2. Cross-check: Every module in DOMAIN_MAP should appear in at least one DECISIONS_LOG entry
3. Cross-check: At least 50% of TRAPS entries should reference a real bug/PR number
4. Ask dev to review: "Anything critical missing? Anything wrong?" — target 5-minute review

### Phase 4: Commit

```bash
git add docs/institutional-memory/
git commit -m "docs: generate institutional memory via /repo-archaeologist

Generated:
- DECISIONS_LOG.md: [N] decisions from [M] PRs
- DOMAIN_MAP.md: [N] modules documented
- TRAPS.md: [N] traps identified

Review: [senior dev name] confirmed accuracy"
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Writing code documentation instead of business knowledge | Ask "would a PM understand this?" — if no, rewrite |
| Missing "Reversal risk" on decisions | Every decision needs this — it's the whole point |
| Traps without code examples | Abstract trap = useless trap. Show wrong vs right code |
| Trying to document everything | Focus on top 20% most critical modules first |
| Domain map uses developer jargon | Write for a new developer who has ZERO context |

## Refresh Schedule

- **Full rescan**: Quarterly, or when project scope changes significantly
- **Incremental updates**: Handled by `/knowledge-capture` on every PR
- **Trap additions**: Immediately after any production bug