Forensic deepdive extract

Skill Dhevenddra/forensic-deepdive/.claude/skills/forensic-deepdive-extract

Run a full forensic deep-dive on an unfamiliar codebase, producing five durable markdown artifacts (MAP.md, HOTPATHS.md, ARCHAEOLOGY.md, MENTAL_MODEL.md, AGENT_BRIEF.md). Use when the user says "analyze this repo", "onboard me to X", "I just joined a new team", "deep-dive this codebase", or clones/opens a repo they haven't worked in before. Do NOT use if the repo already has fresh artifacts under docs/codebase/ less than 7 days old — use forensic-deepdive-query instead.From its SKILL.md

Install

npx -y skills add Dhevenddra/forensic-deepdive --skill forensic-deepdive-extract

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.4 KB, as published. Nobody here has run it

Forensic Deep-Dive — Extract

Runs the full extraction pipeline once per new codebase. Produces five markdown artifacts in docs/codebase/.

When to use

First time analyzing this codebase.
Repo has no docs/codebase/ directory.
Existing artifacts are >7 days old AND >100 commits behind HEAD.

When NOT to use

Artifacts exist and are <7 days old → use forensic-deepdive-query.
Only some files changed since last run → use forensic-deepdive-update.
User is asking about a single file or function → just read it.

How to run

Verify CLI is installed:
```
forensic --version
```
If missing: uv tool install forensic-deepdive or pipx install forensic-deepdive.

From the repo root:

forensic extract . --output ./docs/codebase/

Defaults:
- Cloud mode (uses ANTHROPIC_API_KEY or OPENAI_API_KEY).
- Plain git log archaeology (no Graphiti).
- Repomix --compress for flattening.
Flags:
- --local — use Ollama / LM Studio on localhost (v0.2).
- --with-graphiti — enable temporal KG (v0.2; only if repo meets 2-of-5 threshold).
- --fast — use yek instead of Repomix (v0.2).
- --force — ignore cache, regenerate everything.

Pipeline stages

Stage	Flag	Typical time
Inventory	`--stage=inventory`	<10s
Layer 1 (Tree-sitter + PageRank)	`--stage=static`	30s–5min
Layer 2 (Repomix --compress)	`--stage=flatten`	10s–2min
Layer 3 (plain-git / Graphiti)	`--stage=history`	30s plain / 5-15min Graphiti
Layer 4 (emit 5 artifacts)	`--stage=emit`	10–60s

Earlier stages cache to .forensic-deepdive/cache/.

What to report back to the user

After the run completes:

Five-bullet summary: "Top entry points are X, Y, Z. Hot paths are A, B. The repo's hidden weight-bearing abstraction is C."
Cost report: read .forensic-deepdive/last_run.json and report actual token cost.
Three suggested first-tasks based on ARCHAEOLOGY.md (e.g., "PR #1234 was reverted; underlying bug may still exist in module M").
Exact paths of the five artifacts.
Shim status: confirm CLAUDE.md, AGENTS.md, .cursor/rules/codebase.mdc, .continue/rules/codebase.md were written.

Non-Claude harness fallback

If the user's harness is Codex CLI / Cursor / Continue / Aider:

Tell them to run forensic extract . --output ./docs/codebase/ in their shell.
Every harness can drive a CLI. Do not assume MCP tools are available.

Pitfalls

❌ Don't regenerate MENTAL_MODEL.md more than once a week without --force. New hires depend on its stability.
❌ Don't commit .forensic-deepdive/cache/ (already in .gitignore template).
❌ Don't run on a repo with uncommitted changes you care about — tool only reads, but --with-graphiti may spin up Docker.
❌ Don't assume the AGENT_BRIEF.md ≤5kb cap is "guidance" — it's enforced in CI.