@docsworth/cli 0.0.0-stage → 0.2.0

package/plugin/skills/update-after-incident/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: update-after-incident
+description: After an incident or postmortem, find the runbooks and service pages it touched and propose corrections to each as pull requests for the owning teams. Use when someone says "update the docs after this incident", "the runbook was wrong during the outage", or shares a postmortem and asks what knowledge needs fixing.
+---
+
+# Update knowledge after an incident
+
+Incidents are when runbooks prove wrong. The goal is a small, reviewable PR on each
+affected page, each with its evidence from the incident. A rewrite is never the goal.
+
+## 1. Extract what actually happened
+
+From the postmortem or notes the user gave you, list:
+
+- the symptoms and alerts
+- the services involved
+- every command or step responders actually ran
+- what didn't work, and what they did instead
+- any new check or rollback they discovered
+
+## 2. Find the affected pages
+
+Use the Docsworth `search` tool with the symptoms, then with each service name, passing
+`include_stale: true`. `read` every candidate. A page is affected when the incident
+showed that one of these is wrong or missing:
+
+- a step
+- a command
+- a threshold
+- a check
+- a rollback
+
+The search results also list excluded pages: overdue, deprecated or draft. Tell the
+user which of those the incident touched and which team owns each. An overdue runbook
+that failed during an incident is the most important thing to surface.
+
+## 3. Propose edits, one PR per page
+
+For each affected page, call `propose_edit` with:
+
+- **`edits`:** exact `old` → `new` replacements. Copy `old` verbatim from the `read`
+  result, and include enough surrounding text that it matches exactly once. Prefer
+  several small edits to replacing the whole `content`.
+- **`reason`:** the incident id or date, what happened, and which edit fixes what.
+  Reviewers read this first.
+- **`draft`:** `true` when you're unsure whether a change is right.
+
+Never try to change `id`, `owner_team`, `acl` or `last_verified`; the tool refuses.
+Verification belongs to the owners, through the `verify` tool.
+
+If `propose_edit` refuses because this session read pages with a narrower audience,
+don't work around it. Tell the user which page needs the edit and let them open it
+separately.
+
+## 4. Report
+
+List each PR URL with its page and owning team. Then list the gaps the incident
+revealed where no page exists yet. Each gap is a candidate for the `draft-runbook`
+skill.

package/plugin/skills/verify-page/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: verify-page
+description: Walk a page's owner through checking that a knowledge page is still true, fix what is not via a proposed edit, then open the verify PR that resets its review clock. Use when someone says "verify this runbook", "this page is overdue", "re-verify our team's docs", or after the weekly owner digest lists pages due for review.
+---
+
+# Verify a page
+
+Verification is the owning team saying "this is still true", and it's what lets agents
+cite the page. Only a member of the page's `owner_team` can verify it. The `verify` tool
+enforces that, so check membership before doing a long walkthrough.
+
+## 1. Pick the page
+
+If the user named a page, `read` it. If they named a team, call `stale` with
+`owner_team` and offer the overdue pages oldest first, then the pages that are due soon.
+Show the page's `owner_team`, `last_verified`, `due` and `flags` before starting.
+
+## 2. Walk through it with the owner
+
+Go section by section: *When to use*, *Steps*, *Checks*, *Rollback*. For each one, ask
+the owner a concrete question rather than "is this right?". For example:
+
+- "Is `shipyard deploy` still the command?"
+- "Is the canary still 5% → 25% → 100%?"
+- "Does this alert still exist under this name?"
+
+Where a step names something you can check without changing anything, offer to check it
+and run it only after the owner agrees. Examples are a CLI's `--help`, a file in the
+repo, or a dashboard URL. Never run a mutating command as part of verification.
+
+Record every answer. Anything wrong or out of date becomes an edit in step 3.
+
+## 3. Fix first, then verify
+
+- **If anything needs changing:** call `propose_edit` with the exact edits and a
+  `reason` that says it came from verification. Verify only once those changes are
+  agreed. Verifying a page you know is wrong defeats the gate.
+- **If everything is still true:** call `verify` with the page id. It opens a PR that
+  sets `last_verified` to today. If it's refused because the user isn't on the owning
+  team, say which team can verify it and stop.
+
+## 4. Report
+
+Give the PR URL or URLs, the new review due date, and anything the owner was unsure
+about. Log the unsure items as `TODO(owner):` lines in a proposed edit rather than
+dropping them.

package/templates/github/knowledge.yml

@@ -0,0 +1,51 @@
+# Docsworth CI for a knowledge repo. Copy to .github/workflows/knowledge.yml
+# (`docsworth init --ci` does this).
+#  - Pull requests: lint frontmatter, ownership and links; dry-run the skills compiler.
+#  - Merges to the default branch: recompile skills and commit any changes.
+#    If the default branch is protected against bot pushes, replace the commit step
+#    with a PR (e.g. peter-evans/create-pull-request) or publish skills as an artifact.
+name: knowledge
+
+on:
+  pull_request:
+    paths: ["knowledge/**", "CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS", ".knowledge/config.yaml"]
+  push:
+    branches: [main]
+    paths: ["knowledge/**"]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+      - run: npx -y "__DOCSWORTH_PACKAGE__" lint .
+      - run: npx -y "__DOCSWORTH_PACKAGE__" compile . --dry-run
+
+  compile:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 22
+      - run: npx -y "__DOCSWORTH_PACKAGE__" compile .
+      - run: npx -y "__DOCSWORTH_PACKAGE__" compile . --check
+      - name: Commit regenerated skills
+        run: |
+          if [ -n "$(git status --porcelain -- skills)" ]; then
+            git config user.name "docsworth[bot]"
+            git config user.email "docsworth-bot@users.noreply.github.com"
+            git add skills
+            git commit -m "skills: recompile from knowledge [skip ci]"
+            git push
+          fi