docbridge 0.4.0

package/templates/skills/docbridge-link/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: docbridge-link
+description: Link existing Markdown specification sections to existing supported code declarations. Use for docs-first candidate discovery, section-level confirmation, and adding @doc/@code annotations to existing projects.
+---
+
+# docbridge-link
+
+Create DocBridge annotations for existing docs and code. Work docs-first: choose
+Markdown sections that look like specifications, then propose supported
+TypeScript, Swift, or Dart declarations that implement or represent each
+section.
+
+Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
+repo recipe such as `just check`, or
+`bun run /path/to/docbridge/src/cli/index.ts`.
+
+## Procedure
+
+1. **Determine docs scope.** Use the scope confirmed by `docbridge-adopt` when
+   available. Otherwise, inspect the repository and ask the user to confirm the
+   docs directories/files before proposing links.
+
+2. **Find section candidates.**
+   - Prioritize unlinked sections.
+   - Include already linked sections at lower priority when an additional link
+     may be justified.
+   - Ignore sections that are clearly prose-only, changelog entries, runbook
+     steps, or project process unless the user says they are specifications.
+
+3. **For each candidate section, propose up to three code symbols.** Base the
+   ranking on:
+   - heading text and section body
+   - exported symbol names
+   - existing JSDoc and nearby comments
+   - file paths and directory names
+   - implementation body only when the surrounding information is insufficient
+
+   Include both:
+   - why the symbol may match
+   - what remains uncertain
+
+4. **Ask for section-level decisions.** Present 5-10 section candidates at a
+   time. For each section the user can choose:
+   - adopt: select one or more code symbols to link
+   - exclude: do not link this section
+   - hold: keep undecided for later
+
+   The user may also name a symbol not in the proposed top three.
+
+5. **Classify no-match sections.** If no reasonable exported symbol exists,
+   report the likely reason instead of forcing a link:
+   - not implemented yet
+   - spans multiple symbols without a clear public representative
+   - likely stale docs
+   - not a specification section
+   - target appears internal or not exported
+
+6. **Add annotations only after confirmation.**
+   - Add `@code` directly above the Markdown heading, as the nearest comment
+     to the heading.
+   - Add `@doc` to the code declaration's documentation comment.
+   - If the declaration has no documentation comment, create a minimal one
+     containing only `@doc`, using the language's documentation comment form.
+   - If the pair already exists on one side, show it and, after confirmation,
+     add the missing backlink.
+   - Preserve existing annotations; do not replace or clean up suspicious links
+     in this skill.
+
+7. **Verify.** Run `docbridge check`, then inspect the affected links with
+   `docbridge context` or `docbridge graph --json --include-content` for the
+   changed files. Report any remaining diagnostics or semantic uncertainty.
+
+## Boundaries
+
+- Do not split Markdown sections or rename headings. If a section is too broad
+  or ambiguous, classify it as held or no-match.
+- Multiple code symbols may link to one docs section when each role is clear.
+- One code symbol may link to multiple docs sections when each section covers a
+  distinct specification aspect.
+- Do not link solely because names are similar.

package/templates/skills/docbridge-review/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: docbridge-review
+description: Review all existing DocBridge links for semantic validity. Use after adoption or periodically to find valid-but-wrong links, stale docs, excessive links, or ambiguous docs/code relationships.
+---
+
+# docbridge-review
+
+Review the semantic validity of the entire DocBridge graph. This is not a
+change-set or pull-request review. It checks whether valid links actually
+connect a docs section to the code symbol that implements or represents that
+specification.
+
+This skill requires `docbridge graph --json --include-content`.
+
+## Procedure
+
+1. **Build the graph.**
+
+   ```sh
+   docbridge graph --json --include-content
+   ```
+
+   If the repository uses a wrapper, use the native invocation instead. Read
+   `diagnostics` first. Mechanical failures from `docbridge check` should be
+   fixed or acknowledged before relying on semantic findings.
+
+2. **Batch by docs file.** Review all links, but process them in batches:
+   - docs file is the default batch boundary
+   - split a batch further when it contains too many sections or links
+   - keep notes so repeated patterns are applied consistently across batches
+
+3. **Read both sides.**
+   - For docs nodes, use the graph range to read the full Markdown section.
+   - For code nodes, start with graph content: JSDoc plus signature. Read the
+     implementation only when necessary to judge the relationship.
+   - Compare behavior, contract, input/output, constraints, and design intent.
+
+4. **Classify findings.**
+   - High: clearly wrong link, stale docs fixed in place by a link, or a link
+     to a section that is not a specification.
+   - Medium: partial overlap, unclear representative symbol, overly broad
+     section, or multiple linked symbols with ambiguous roles.
+   - Low: cleanup opportunity, duplicate docs, excessive links, or missing
+     explanation of why multiple links are needed.
+
+5. **Report findings and fixes.** For each finding include:
+   - severity
+   - doc endpoint and code endpoint
+   - evidence from both sides
+   - recommended fix
+
+   Do not edit annotations automatically. If the user approves a fix, use
+   `docbridge-link` or `docbridge-annotate` rules to make the change.
+
+## Principles
+
+- `docbridge check` proves link mechanics; this skill reviews meaning.
+- Do not rubber-stamp links because the target resolves.
+- Do not delete annotations merely to silence uncertainty. Explain the
+  uncertainty and ask for a decision.
+- Prefer fewer, clearer links over broad many-to-many links without explicit
+  roles.

package/templates/skills/docbridge-sync/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: docbridge-sync
+description: Triage DocBridge related-gate findings — linked counterparts of changed files that were not themselves updated. Use when a Stop-hook message, CI comment, or docbridge related --gate run flags unchanged counterparts, to judge divergence with docbridge context and then update or justify each one.
+---
+
+# docbridge-sync
+
+Resolve `docbridge related --gate` findings. A gate violation means a changed
+file has a linked counterpart that nobody updated — it does **not** mean the
+counterpart must change; it means nobody has decided yet. This skill makes
+that decision explicit, per counterpart.
+
+Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
+repo recipe such as `just related-gate`, or
+`bun run /path/to/docbridge/src/cli/index.ts`.
+
+## Procedure
+
+1. **Collect the violations.** Use the gate report you were given (Stop-hook
+   message, CI comment), or produce one over the change set:
+
+   ```sh
+   git diff --name-only HEAD | docbridge related --stdin --gate
+   ```
+
+   Each violation names a changed endpoint and its unchanged counterpart
+   endpoint.
+
+2. **Fetch the counterpart content.** If the report did not include it, run
+   the context command over the changed files; its output is the counterparts'
+   content:
+
+   ```sh
+   git diff --name-only HEAD | docbridge context --stdin
+   ```
+
+   Read the block for each flagged counterpart: the full spec section for a
+   doc counterpart, the full declaration including JSDoc for a code one.
+
+3. **Judge divergence, per counterpart.** Compare what the counterpart says
+   with what the change did:
+   - Behavior, contract, format, or constraint described by the counterpart no
+     longer matches → **update the counterpart** in the same change set.
+   - The change is internal (refactoring, comments, test-only, formatting) and
+     every documented statement still holds → **no update**, with a written
+     justification.
+   - The link itself is wrong (points at the wrong section or symbol) → fix
+     the annotation pair instead; follow the `docbridge-annotate` skill.
+
+4. **Re-run the gate** after updates. Counterparts you edited leave the
+   violation list; what remains must be covered by justifications.
+
+5. **Report every decision.** In the final response (and the PR description
+   when one exists), list each flagged counterpart with either the update made
+   or the justification. A justification must reference the counterpart's
+   actual content ("the section documents the exit codes, which this change
+   does not alter"), not just assert irrelevance.
+
+## Principles
+
+- Never silence a violation by deleting or rewriting annotations to detach
+  the link; that defeats the graph the gate protects.
+- Do not rubber-stamp: if the counterpart content was not read, the judgment
+  has no basis.
+- Updating a spec section to match changed code is a *decision about the
+  contract*, not bookkeeping — when the change contradicts an explicit
+  documented promise, surface it to the user instead of quietly rewriting the
+  promise.