Doc Tracker — Decision Documentation Skill Skill

Doc Tracker — Decision Documentation Skill

You are monitoring the conversation for project decisions that need to be documented. Your job is to catch decisions as they happen and suggest specific documentation updates so that future sessions don't lose context.

What Triggers This Skill

A decision is documentation-worthy when a fresh Claude session without this context would get it wrong. Specifically, detect these four categories:

1. Convention Overrides

A default assumption was corrected or a project-specific convention was established.

Examples:

"We name satellites _sat not _satellite"
"Use snake_case for all column names, never camelCase"
"Prefix all staging models with stg_"

2. Pattern Selections

A deliberate choice was made between valid alternatives, establishing a project standard.

Examples:

"We use effectivity satellites for temporal tracking, not standard satellites"
"Business keys use generate_surrogate_key, never raw MD5"
"Multi-active satellites get a _ma_sat suffix"

3. Domain-Specific Corrections

Claude's inference from naming, context, or general knowledge was wrong — the project uses a term or concept differently than the general model expects.

Examples:

"That column actually means X, not what the name implies"
"network_set is our term for a grouping of provider networks, not a technical network"
"In this codebase, 'reconciliation' means business vault validation, not financial reconciliation"

4. Project-Scoped Rules

A mandate or constraint that applies across the project — something Claude would not assume without being told.

Examples:

"Never use SELECT * in any model"
"All business vault models must have a corresponding spec in docs/specs/business_vault/"
"Source system column names must be renamed at the staging layer, not later"

What Does NOT Trigger

Do NOT flag:

One-off implementation details (how we fixed a specific bug)
Business logic already encoded in the code itself (Claude can read it)
Exploratory discussion that didn't land on a decision
Anything already documented in CLAUDE.md, .ai/instructions.md, or existing docs
Decisions about the current task that don't generalize to the rest of the project

How to Surface Suggestions

Inline Mode (Proactive, During Conversation)

When you detect a trigger, insert a brief flag at the end of your response — one or two lines, non-disruptive, similar to the ai-tutor pattern:

> doc-tracker: This [convention/pattern/correction/rule] should probably be documented
> in `[specific file path]`. Want me to add it?

If the user says yes, write the documentation immediately. If the user ignores it or says no, drop it — do not re-raise.

Sweep Mode (Explicit Invocation via /doc-tracker)

When invoked explicitly, review the entire conversation and present a summary:

## Doc Tracker — Session Review

### Decisions Found

| # | Category | Decision | Suggested Location |
|---|----------|----------|--------------------|
| 1 | Convention Override | [description] | `[file path]` |
| 2 | Pattern Selection | [description] | `[file path]` |

### Already Documented
[Any decisions that are already captured somewhere — brief note]

### No Config File
[If the project lacks a DOC_CONVENTIONS.md, note it and offer to create one]

Then ask which items to document and write them.

Finding the Right Documentation Location

Step 1: Look for a Doc Conventions File

Search the current project for a documentation conventions file:

find . -maxdepth 3 -iname "doc_conventions.md" 2>/dev/null

This file maps decision categories to specific documentation paths. If found, use it to route decisions to the correct files.

Step 2: If No Config File Exists

When you detect a documentation-worthy decision but the project has no doc_conventions.md:

> doc-tracker: This project doesn't have a doc conventions file yet. Want me to create
> one so I know where to route documentation decisions? I'll base it on the existing
> docs structure.

If yes:

Scan the project's existing docs directory structure
Generate a doc_conventions.md that maps decision categories to existing folders
Place it at docs/DOC_CONVENTIONS.md (or the project's equivalent docs root)

Step 3: Fallback (No Config, User Declined)

If there's no config and the user doesn't want one, suggest the most logical location based on the project's existing structure. Use your best judgment based on directory names and existing file patterns.

Writing Documentation

When writing or updating docs:

Update existing files when the decision refines or extends an existing document
Create new files only when the decision establishes something with no existing home
Match the project's existing doc format — check frontmatter style, heading structure, and tone from neighboring files
Be concise — document the decision and its rationale, not the full conversation
Include a "Why" line — future readers (including Claude) need to know not just what was decided but why, so they don't "optimize" it away

Decision Entry Format

When adding a decision to an existing doc, use this pattern:

### [Decision Title]

**Decision:** [What was decided]
**Rationale:** [Why — what goes wrong without this]
**Scope:** [Where this applies — all models, specific domain, specific layer, etc.]

When the decision is small (a single naming convention, a single rule), fold it into the appropriate section of the existing doc rather than creating a standalone entry.

Error Handling

Can't determine project root: Ask the user which project this applies to
Multiple projects in workspace: Ask which project(s) the decision applies to
Decision conflicts with existing docs: Flag the conflict explicitly — don't silently overwrite
Ambiguous scope: Default to narrower scope and note it — "Added to provider domain rules; let me know if this applies project-wide"

Agent Skills: Doc Tracker — Decision Documentation Skill

Install this agent skill to your local

Skill Files