atomic-claude

Conventions for editing the atomic CLI and command artifacts in this repo. Auto-fires on phrases like "add a CLI subcommand", "wire a new flag", "prompt the user", "add a doctor check", "add a doctor repair", "edit cmd/atomic/main.go", "extend claudeinstall", "add an internal package", "use huh", "add a command", "create a new verb", "add a partial", "render templates", "edit a command", "edit commands/", "create a new command", "edit an agent", "edit agents/", or "add an agent". Contributor-only — never bundled, never installed.

Hypothesis-driven debugging skill. Use when a bug, test failure, crash, or unexpected behavior is reported. Auto-trigger on error pastes or "broken/doesn't work/failing" language. Explicit invocation: /atomic-debug. Output: symptom statement → hypothesis table → cheapest test first → root cause. No symptom-patching. Boundary with atomic-tdd: this skill owns diagnosing an unknown root cause. Once the cause is known and you are writing the fix, that is atomic-tdd's job (failing test first, then the fix).

Test-first discipline. Auto-triggers on "let's implement X", "add feature Y", "fix bug Z", "write a test for", "implement", "build out", and similar pre-code-change phrases. Iron rule: failing test exists before production code. Skip only for pure docs/config changes with an explicit "skipped because:" note. Explicit invocation: /atomic-tdd. Boundary with atomic-debug: this skill owns writing or changing code — new behavior, or a fix whose root cause is already understood. Diagnosing why something is broken (unknown cause) is atomic-debug's job; debug to the root cause first, then return here to write the fix test-first.

Planning-phase visual comparison aid. Renders 2-4 side-by-side variants per decision dimension as a single throwaway, self-contained HTML file and captures the user's pick as typed terminal codes (e.g. "A2 B3"). Auto-fires on phrases like "show me a few options", "mock up some variants", "let me see this side by side", "visual options for", "compare these layouts", "show layout options", "wireframe some choices". Also invoked by /atomic-plan just-in-time when a design question is genuinely visual. Scope is strictly visual choices — mockup, layout, color, spacing, hierarchy, diagram — not conceptual or text decisions, which stay in the terminal.

Compressed code review comments. Cuts noise from PR feedback while preserving the actionable signal. Each comment is one line: location, problem, fix. Use when user says "review this PR", "code review", "review the diff", or invokes /atomic-review. Auto-triggers when reviewing pull requests.

Conversational wiki and capture-bucket routing. Fires when the user wants a place, space, or folder for notes, research, tickets, raw dumps, or knowledge capture — checks the <wikis> block in ~/.claude/CLAUDE.md; if the cwd is under a registered realm, creates the folder as a bucket via `atomic wiki bucket add` rather than a bare mkdir. Also fires on "add a bucket", "set up a karpathy wiki", "karpathy realm", "set up a wiki for my projects", "add this to my wiki", "wiki this", "what does my wiki know about X", "is my wiki stale". Not invoked by other commands — this skill is the conversational entry point for wiki and bucket operations; /refresh-wiki is the synthesis engine.

Compressed commit message generator. Cuts noise from commit messages while preserving intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why" isn't obvious. Use when user says "write a commit", "commit message", "generate commit", or invokes /atomic-commit. Auto-triggers when staging changes.

Evidence-before-claim gate. Auto-triggers when Claude is about to claim "done", "fixed", "passing", "complete", "ready to merge", "looks good", "should work", "should pass", "green", or any synonym. Iron rule: no completion claim without a fresh verification command run in this turn. Explicit invocation: /atomic-verify.

Diagnose and fix broken release-please CI in this repo. Auto-fires on "release-please CI is failing", "release branch is out of date", "release branch is stale", "release PR is red", "release-please broke", "fix the release CI", "release branch CI failing", "version branch is behind", "release PR changelog is wrong", "release PR missing work". Contributor-only — never bundled, never installed.

Diff-driven documentation surface classifier. Given a diff (staged, branch, or range), reads the project's indexed ## Documentation surfaces table from CLAUDE instructions, matches the diff against it, and emits a structured list of proposed edits. Two modes: maintenance (commit flow — stale/incomplete only, never suggests new pages) and authoring (/documentation explicit — full discovery, gap detection, content generation). Auto-fires on "doc this change", "what surfaces does this touch", "doc impact for this diff", "what needs documenting". Also invoked by /documentation (authoring mode) and by ship verbs (maintenance mode, between stage and signals). Boundary: for raw prose drafting (README intro, guide narrative), atomic-prose owns. This skill owns diff-driven surface impact and content generation for stale/incomplete docs.

Voice and tone rules for *enduring narrative documentation* — README.md, docs/guides/, CHANGELOG narrative entries, and any other long-form human-facing markdown that ships in the repo. Clear, direct, technical narrative. No marketing language, no AI-tell phrases, no em dashes, no throat-clearing. Two voices: Claude's TUI replies use atomic output style (terse, fragments); file contents split by surface — narrative docs use this skill, everything else (specs, design docs, CLAUDE.md, signals files) uses terse technical prose. Invoked by /documentation when editing README or guides. Invoked as callee by `atomic-documentation` when surface is human-facing prose. Auto-fires on "draft the README", "write the docs", "improve this prose", "edit the guide".