Dive Tag

Dive Tag

Goal

Maintain a lightweight, cumulative knowledge graph while coding by:

1. Adding @dive comments near meaningful logic
2. Maintaining project metadata in .dive/overview.md and .dive/modules/*.md

Use this skill automatically whenever you modify code.

Required Outputs

1) File-level headers

At the top of any source file you create or substantially modify, add:

@dive-file: 
@dive-rel: 
@dive-rel: 

Comment syntax must match the language:

• Rust/JS/TS/Go/Java/C/C++/C#: //
• Python/Shell/Ruby/YAML/TOML: #
• HTML/XML/Markdown: ``

Examples:

// @dive-file: Validates JWT tokens and creates auth context for requests.
// @dive-rel: Called by src/api/middleware.rs for every authenticated route.
// @dive-rel: Uses src/auth/session.rs to reject revoked sessions.

2) Inline tags

Add @dive: comments for non-trivial logic you write or change.

Format:

@dive: 

Good:

• @dive: Normalizes user input so lookup is case-insensitive
• @dive: Retries DB write once when the first attempt times out

Avoid:

• Restating syntax
• Vague notes like "does stuff"
• Tagging every trivial line

3) System metadata

Create/update .dive/overview.md at the project root.

Required structure:

# System Overview

## Components
- **** -  -> 

## Relationships
-  -> : 

4) Module metadata

Create/update .dive/modules/.md for modules affected by your changes.

Required structure:

#  Module

## Files
- `` - 

## Relationships
-  -> : 

Operating Rules

1. Keep paths project-relative (for example src/auth/jwt.rs).
2. Update metadata incrementally when behavior changes.
3. Preserve existing useful entries; refine instead of replacing wholesale.
4. Prefer directional relationships (A -> B or A <- B) with short context.
5. If .dive/ does not exist, create it with overview.md and modules/.
6. If uncertain, write conservative descriptions and avoid guessing internals.

Minimal Workflow

1. Read existing .dive/overview.md and relevant .dive/modules/*.md if present.
2. Implement code changes.
3. Add/update file headers and inline @dive: tags in touched files.
4. Update .dive/overview.md if component boundaries or interactions changed.
5. Update relevant .dive/modules/*.md for touched files and relationships.

Completion Checklist

• Touched files include accurate @dive-file and @dive-rel headers
• New or changed logic includes meaningful @dive: comments
• .dive/overview.md exists and reflects current component structure
• .dive/modules/*.md exists for touched modules and links to real files

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: iantbutler01
• Source: iantbutler01/code_diver
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.