dive-tag
starsforks
How to install dive-tag?
iantbutler01/code_diver/dive-tag
$npx -y skills add iantbutler01/code_diver --skill dive-tagAdd structured @dive comments and maintain .dive metadata so code changes are explainable and navigable.
SKILL.md
| 1 | # Dive Tag |
| 2 | |
| 3 | ## Goal |
| 4 | |
| 5 | Maintain a lightweight, cumulative knowledge graph while coding by: |
| 6 | |
| 7 | 1. Adding `@dive` comments near meaningful logic |
| 8 | 2. Maintaining project metadata in `.dive/overview.md` and `.dive/modules/*.md` |
| 9 | |
| 10 | Use this skill automatically whenever you modify code. |
| 11 | |
| 12 | ## Required Outputs |
| 13 | |
| 14 | ### 1) File-level headers |
| 15 | |
| 16 | At the top of any source file you create or substantially modify, add: |
| 17 | |
| 18 | ```text |
| 19 | @dive-file: <what this file is responsible for> |
| 20 | @dive-rel: <relationship to another file/module/dependency> |
| 21 | @dive-rel: <another relationship, if relevant> |
| 22 | ``` |
| 23 | |
| 24 | Comment syntax must match the language: |
| 25 | |
| 26 | - Rust/JS/TS/Go/Java/C/C++/C#: `//` |
| 27 | - Python/Shell/Ruby/YAML/TOML: `#` |
| 28 | - HTML/XML/Markdown: `<!-- -->` |
| 29 | |
| 30 | Examples: |
| 31 | |
| 32 | ```rust |
| 33 | // @dive-file: Validates JWT tokens and creates auth context for requests. |
| 34 | // @dive-rel: Called by src/api/middleware.rs for every authenticated route. |
| 35 | // @dive-rel: Uses src/auth/session.rs to reject revoked sessions. |
| 36 | ``` |
| 37 | |
| 38 | ### 2) Inline tags |
| 39 | |
| 40 | Add `@dive:` comments for non-trivial logic you write or change. |
| 41 | |
| 42 | Format: |
| 43 | |
| 44 | ```text |
| 45 | @dive: <plain-English behavior and outcome> |
| 46 | ``` |
| 47 | |
| 48 | Good: |
| 49 | |
| 50 | - `@dive: Normalizes user input so lookup is case-insensitive` |
| 51 | - `@dive: Retries DB write once when the first attempt times out` |
| 52 | |
| 53 | Avoid: |
| 54 | |
| 55 | - Restating syntax |
| 56 | - Vague notes like "does stuff" |
| 57 | - Tagging every trivial line |
| 58 | |
| 59 | ### 3) System metadata |
| 60 | |
| 61 | Create/update `.dive/overview.md` at the project root. |
| 62 | |
| 63 | Required structure: |
| 64 | |
| 65 | ```markdown |
| 66 | # System Overview |
| 67 | <brief system description> |
| 68 | |
| 69 | ## Components |
| 70 | - **<Component>** - <responsibility> -> <path> |
| 71 | |
| 72 | ## Relationships |
| 73 | - <Component A> -> <Component B>: <how they interact> |
| 74 | ``` |
| 75 | |
| 76 | ### 4) Module metadata |
| 77 | |
| 78 | Create/update `.dive/modules/<module>.md` for modules affected by your changes. |
| 79 | |
| 80 | Required structure: |
| 81 | |
| 82 | ```markdown |
| 83 | # <Module> Module |
| 84 | <module purpose> |
| 85 | |
| 86 | ## Files |
| 87 | - `<relative/path>` - <file responsibility> |
| 88 | |
| 89 | ## Relationships |
| 90 | - <file A> -> <file B>: <dependency or call flow> |
| 91 | ``` |
| 92 | |
| 93 | ## Operating Rules |
| 94 | |
| 95 | 1. Keep paths project-relative (for example `src/auth/jwt.rs`). |
| 96 | 2. Update metadata incrementally when behavior changes. |
| 97 | 3. Preserve existing useful entries; refine instead of replacing wholesale. |
| 98 | 4. Prefer directional relationships (`A -> B` or `A <- B`) with short context. |
| 99 | 5. If `.dive/` does not exist, create it with `overview.md` and `modules/`. |
| 100 | 6. If uncertain, write conservative descriptions and avoid guessing internals. |
| 101 | |
| 102 | ## Minimal Workflow |
| 103 | |
| 104 | 1. Read existing `.dive/overview.md` and relevant `.dive/modules/*.md` if present. |
| 105 | 2. Implement code changes. |
| 106 | 3. Add/update file headers and inline `@dive:` tags in touched files. |
| 107 | 4. Update `.dive/overview.md` if component boundaries or interactions changed. |
| 108 | 5. Update relevant `.dive/modules/*.md` for touched files and relationships. |
| 109 | |
| 110 | ## Completion Checklist |
| 111 | |
| 112 | - Touched files include accurate `@dive-file` and `@dive-rel` headers |
| 113 | - New or changed logic includes meaningful `@dive:` comments |
| 114 | - `.dive/overview.md` exists and reflects current component structure |
| 115 | - `.dive/modules/*.md` exists for touched modules and links to real files |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
