Deep dive

Deep Dive

Use this skill to turn repository exploration into durable project memory. It is a companion to the brain skill, not a standalone codebase-summary skill.

Primary output: <brain-vault-path>/projects/<slug>/_<slug>.md.

Optional output: companion notes such as conventions.md, gotchas.md, testing.md, or architecture.md only when the content earns its own file.

Preconditions

• The brain skill is available and its vault placeholders are configured.
• You can read the repository being analyzed.
• You can write to <brain-vault-path>.

If any precondition is missing, stop and ask the user for the missing configuration rather than inventing paths.

When To Use

• The user explicitly asks for a deep dive, onboarding pass, or durable repo understanding.
• The current repo has no matching projects/<slug>/ folder in the brain vault and upcoming work would benefit from persistent context.
• Existing project notes are stale enough that incremental brain capture would leave contradictions.

Do not use this for quick code questions, small bug fixes, or ephemeral summaries. Use normal ad-hoc exploration instead.

Principles

• Verified facts only. Read files before writing claims. Put uncertainty in Open questions.
• Minimum viable memory first. A useful _ <slug>.md entry point beats a sprawling folder of half-filled notes.
• Update in place. If project notes already exist, revise them rather than creating duplicates.
• Link, don't mirror. Point to repo docs instead of copying their contents into the brain.
• Companion notes are earned. Create extra files only for substantial, reusable topics.
• No secrets. Do not store credentials, private data, raw logs, database dumps, or secret-bearing screenshots.

Workflow

1. Identify The Project

1. Determine the repo root.
2. Derive <slug> from the repo root folder name using the brain skill's kebab-case rules.
3. Check for existing notes at <brain-vault-path>/projects/<slug>/.
4. If notes exist, read _ <slug>.md first, then any relevant companion files.

Use existing notes as a starting point, not as ground truth when the repo has drifted.

2. Explore The Repo

Find enough evidence to answer the project-entry sections below. Prefer reading actual source/config/docs over inferring from filenames.

Minimum exploration checklist:

• Top-level layout and purpose of important directories.
• Languages, runtimes, frameworks, package managers, and build systems.
• Entry points: apps, services, CLIs, libraries, workers, jobs, exports.
• How to run tests, build, lint, and start local development when discoverable.
• Configuration and environment shape, without copying secrets.
• External dependencies and integrations.
• Existing docs: README, architecture docs, ADRs, contributing docs, runbooks.
• Non-obvious conventions, gotchas, or load-bearing weirdness.
• Current target state or active direction if it is clear from docs/code/session context.

For large repos, use subagents or parallel exploration by subsystem. For small repos, direct reads are enough.

3. Write The Entry Point

Create or update:

<brain-vault-path>/projects/<slug>/_<slug>.md

Use this shape:

---
created: YYYY-MM-DD
updated: YYYY-MM-DD
kind: service|library|app|tool|monorepo|other
stack: [language, runtime, key-frameworks]
status: active|dormant|archived
depends_on: []
used_by: []
---

# <slug>

## Purpose
## Architecture
## Tech stack
## Layout
## How to work on it
## Relationships
## Target state
## Gotchas
## Open questions
## Notes for future-you
## Companion notes and references

#project/<slug>

Guidance:

• Keep the entry point scannable. It should let future-you regain the project model quickly.
• Include concrete commands only when verified from the repo.
• Use Open questions for unresolved or ambiguous facts.
• If repo docs already explain something well, link to the file path and summarize only what future-you needs to know.

4. Add Companion Notes Only If Useful

Create companion notes when a topic is too large or important for the entry point.

Common examples:

• architecture.md for detailed subsystem/data-flow notes.
• conventions.md for stable project-specific coding/test/naming patterns.
• gotchas.md for traps future-you is likely to hit.
• testing.md for non-obvious test setup or coverage strategy.
• deploy.md for release/deployment mechanics.
• references.md when several external links or artifacts matter.

Rules:

• Every project-scoped markdown note ends with #project/<slug>.
• Link every companion note from _ <slug>.md.
• Path-qualify links whose basename is common across projects, e.g. [[projects/<slug>/gotchas|gotchas]].
• Do not create empty stubs for completeness.

5. Register The Project

If this is a new project, update <brain-vault-path>/index.md with a short link under the appropriate project status section.

If relationships were discovered, update the relevant depends_on / used_by frontmatter in affected project notes when those notes exist.

6. Verify Lightly

Do a lightweight correctness pass:

1. Re-read _ <slug>.md.
2. Confirm it answers: what is this, how is it shaped, how do I work on it, what should future-you not miss?
3. Confirm all project-scoped notes have #project/<slug>.
4. Confirm links to companion notes resolve by path or unique filename.

Use Obsidian CLI checks only if configured and helpful:

obsidian vault=<brain-vault-name> unresolved
obsidian vault=<brain-vault-name> backlinks path=projects/<slug>/_<slug>.md

Do not block completion on graph colors, attachments, or exhaustive backlink hygiene unless the user explicitly asks for vault maintenance.

Report Back

Keep the final report concise:

• Project slug and entry note path.
• Companion notes created or updated.
• Important open questions.
• Anything deliberately skipped, such as unconfigured Obsidian CLI checks or missing docs.

Escalation Paths

• If the repo is too large for one pass, write the entry point with what is verified and list remaining subsystems in Open questions.
• If existing notes conflict with the repo, prefer the repo and update the notes; mention the correction in the report.
• If a topic becomes operationally important during exploration, use normal brain capture rules after the deep dive completes.