docbridge 0.7.0 → 0.9.0

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

@@ -1,62 +0,0 @@
----
-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

@@ -1,68 +0,0 @@
----
-name: docbridge-sync
-description: Triage DocBridge related-gate findings — linked counterparts of changed files that were not themselves updated. Use when a Git hook, 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 (a Git
-   hook's output, a 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.