Sync Docs
Keep the agent-facing documentation under docs/ accurate as the implementation
evolves. This skill is diff-driven (it only looks at source that changed since
a committed baseline) and deliberately conservative (it makes the smallest
edits needed to restore accuracy — it does not rewrite, restyle, or expand the
docs).
Read docs/README.md first for the doc set's structure and intent. The docs are
written for AI agents to read, are plain Markdown, and are designed to be
verifiable: each file lists Keywords/Related, and the reference/ files name
their source-of-truth.
Guiding principle: be conservative
The goal is to keep facts correct with low churn, not to perfect the prose.
- Default to leaving a doc unchanged. Only edit when a documented fact is now
demonstrably wrong, a documented feature was removed, or a clearly
significant new user-facing feature/shortcut/setting was added.
- Make the smallest possible edit. Fix the wrong cell/line; don't reflow
tables, reorder sections, or reword surrounding prose.
- Tolerate a wide range. Ignore internal refactors, renames, and code
reshuffles that don't change user-facing behavior. Ignore stylistic/wording
differences. Approximate phrasings ("roughly", "typically", "best-effort") are
fine — don't tighten them just because you can.
- Don't grow the doc set casually. Do not add new sections or new files unless
a genuinely new top-level feature appeared. If a change is large (a new feature
that needs a whole new component manual, or a structural overhaul), do not do
it silently — describe it in the report and let the human decide.
- Keep "source of truth" pointers correct if files move or are renamed.
- Prefer touching few files per run. If you find yourself about to edit many
files, stop and re-read this section — most of those are probably tolerable.
Steps
Read the baseline. Open docs/.sync-meta.json and read the
last_synced_commit field (the last-synced commit hash).
Diff the implementation since the baseline. List source files that changed:
git diff --name-only <baseline_commit>..HEAD -- \
supacode/ ProwlCLI/ Package.swift Resources/git-wt
If nothing relevant changed, report "Docs up to date as of <HEAD>." then go
to step 6 (bump the baseline) and stop.
Map changed source → docs to re-check. Use this table; only open the docs
whose source actually changed. (Most changes touch zero or one doc.)
| Source that changed |
Docs to re-check |
supacode/App/AppShortcuts.swift, supacode/Commands/** |
reference/keyboard-shortcuts.md (+ shortcut mentions in the relevant components/*.md) |
supacode/Features/Settings/Models/GlobalSettings.swift, RepositorySettings.swift, UserRepositorySettings.swift |
reference/settings-fields.md, components/settings.md, components/custom-actions.md |
ProwlCLI/**, supacode/CLIService/** |
components/cli.md |
supacode/Clients/CLIInstall/** |
components/cli.md, components/settings.md |
supacode/Features/Repositories/**, supacode/Domain/Worktree*.swift, supacode/Domain/Repository*.swift, supacode/Clients/Git/**, Resources/git-wt |
components/repositories-and-worktrees.md |
supacode/Features/Terminal/**, supacode/Infrastructure/Ghostty/** |
components/terminal.md |
supacode/Features/Canvas/** |
components/canvas.md |
supacode/Features/Shelf/** |
components/shelf.md |
supacode/Features/CommandPalette/** |
components/command-palette.md |
supacode/Features/ActiveAgents/** |
components/active-agents.md |
supacode/Domain/AgentDetection/**, supacode/Infrastructure/AgentDetection/** |
components/agent-detection.md |
supacode/Clients/Notifications/**, WorktreeTerminalState+Notifications.swift, supacode/Clients/Dock/** |
components/notifications.md |
supacode/Features/DiffView/** |
components/diff-view.md |
supacode/Clients/Github/** |
components/github-pull-requests.md |
supacode/Clients/Updates/**, supacode/Features/Updates/** |
components/updates.md |
view-mode switching (supacode/Features/App/**, ContentView.swift) |
components/view-modes.md |
overview.md, concepts.md, and README.md only need touch-ups for the
addition/removal of a major feature — leave them alone otherwise.
Verify against the source of truth. For each doc identified, check its
falsifiable claims against the authoritative source — not against the diff
summary — and apply minimal edits per the conservative rules above:
| Claim type |
Source of truth |
| Keyboard shortcuts (key + modifiers + command ID, remappability) |
supacode/App/AppShortcuts.swift; menu wiring in supacode/Commands/*.swift |
| Settings field names / types / defaults |
supacode/Features/Settings/Models/GlobalSettings.swift, RepositorySettings.swift |
| CLI commands / flags / ranges / error codes / JSON fields |
ProwlCLI/** and supacode/CLIService/** (and, if the CLI is installed, prowl <cmd> --help for confirmation) |
| Feature behavior / entry points |
the corresponding supacode/Features/** or supacode/Clients/** |
When in doubt whether something is a real, user-facing change, leave the doc
as-is and flag it in the report rather than editing.
Check internal links if files moved. If you renamed/added/removed any doc
file, re-run a quick relative-link check so nothing in docs/ is broken.
Bump the baseline. Set last_synced_commit (and last_synced_date, note)
in docs/.sync-meta.json to the current HEAD. This file is committed to
git so the baseline persists across sessions and machines — never leave it
uncommitted.
Report. Output a short summary:
## Docs Sync
Baseline: <old_hash> → <new_hash>
Source files changed in range: <count>
### Updated
- docs/<file> — <one-line what & why>
### Checked, left unchanged (tolerated)
- <area> — <why it didn't need a doc change>
### Needs human decision (not applied)
- <large/ambiguous change> — <what & suggested doc action>
Committing
- Standalone run: stage and commit only
docs/** (which includes
docs/.sync-meta.json); never git add .. If anything in docs/ changed and
you're not on main, open a PR targeting onevcat/Prowl.
- As part of release prep (the
release skill, on main): commit the doc +
docs/.sync-meta.json changes as their own commit before the version bump and
tag — e.g. git commit -m "Sync docs for <VERSION>". Do not leave them
staged/uncommitted: release.sh aborts on a dirty working tree, and the doc
commit must already be on main so it becomes an ancestor of the tag and ships
inside the release. Bump/tag happen after, never before.
- Always bump and commit
docs/.sync-meta.json even when no doc edits were
needed, so the next run starts from a tight diff range. The baseline records the
commit the docs were verified against (the current HEAD at run time) — for a
release that is the code being shipped, captured before the later doc/bump/tag
commits, which is correct (those commits touch no implementation files).
1---2name: sync-docs3description: Keep the agent-facing manual under docs/ in sync with the implementation. Diff-driven from a committed commit baseline; makes conservative, minimal edits only where the code has actually changed user-facing behavior. Run on demand or as part of release prep.4---56# Sync Docs78Keep the agent-facing documentation under `docs/` accurate as the implementation9evolves. This skill is **diff-driven** (it only looks at source that changed since10a committed baseline) and **deliberately conservative** (it makes the smallest11edits needed to restore accuracy — it does not rewrite, restyle, or expand the12docs).1314Read `docs/README.md` first for the doc set's structure and intent. The docs are15written **for AI agents to read**, are plain Markdown, and are designed to be16verifiable: each file lists `Keywords`/`Related`, and the `reference/` files name17their source-of-truth.1819## Guiding principle: be conservative2021The goal is to keep facts correct with **low churn**, not to perfect the prose.2223- **Default to leaving a doc unchanged.** Only edit when a documented fact is now24 demonstrably **wrong**, a documented feature was **removed**, or a clearly25 significant new user-facing feature/shortcut/setting was **added**.26- **Make the smallest possible edit.** Fix the wrong cell/line; don't reflow27 tables, reorder sections, or reword surrounding prose.28- **Tolerate a wide range.** Ignore internal refactors, renames, and code29 reshuffles that don't change user-facing behavior. Ignore stylistic/wording30 differences. Approximate phrasings ("roughly", "typically", "best-effort") are31 fine — don't tighten them just because you can.32- **Don't grow the doc set casually.** Do not add new sections or new files unless33 a genuinely new top-level feature appeared. If a change is large (a new feature34 that needs a whole new component manual, or a structural overhaul), **do not do35 it silently** — describe it in the report and let the human decide.36- **Keep "source of truth" pointers correct** if files move or are renamed.37- Prefer touching **few files per run**. If you find yourself about to edit many38 files, stop and re-read this section — most of those are probably tolerable.3940## Steps41421. **Read the baseline.** Open `docs/.sync-meta.json` and read the43 `last_synced_commit` field (the **last-synced commit** hash).44452. **Diff the implementation since the baseline.** List source files that changed:46 ```bash47 git diff --name-only <baseline_commit>..HEAD -- \48 supacode/ ProwlCLI/ Package.swift Resources/git-wt49 ```50 If nothing relevant changed, report "Docs up to date as of `<HEAD>`." then go51 to step 6 (bump the baseline) and stop.52533. **Map changed source → docs to re-check.** Use this table; only open the docs54 whose source actually changed. (Most changes touch zero or one doc.)5556 | Source that changed | Docs to re-check |57 |---------------------|------------------|58 | `supacode/App/AppShortcuts.swift`, `supacode/Commands/**` | `reference/keyboard-shortcuts.md` (+ shortcut mentions in the relevant `components/*.md`) |59 | `supacode/Features/Settings/Models/GlobalSettings.swift`, `RepositorySettings.swift`, `UserRepositorySettings.swift` | `reference/settings-fields.md`, `components/settings.md`, `components/custom-actions.md` |60 | `ProwlCLI/**`, `supacode/CLIService/**` | `components/cli.md` |61 | `supacode/Clients/CLIInstall/**` | `components/cli.md`, `components/settings.md` |62 | `supacode/Features/Repositories/**`, `supacode/Domain/Worktree*.swift`, `supacode/Domain/Repository*.swift`, `supacode/Clients/Git/**`, `Resources/git-wt` | `components/repositories-and-worktrees.md` |63 | `supacode/Features/Terminal/**`, `supacode/Infrastructure/Ghostty/**` | `components/terminal.md` |64 | `supacode/Features/Canvas/**` | `components/canvas.md` |65 | `supacode/Features/Shelf/**` | `components/shelf.md` |66 | `supacode/Features/CommandPalette/**` | `components/command-palette.md` |67 | `supacode/Features/ActiveAgents/**` | `components/active-agents.md` |68 | `supacode/Domain/AgentDetection/**`, `supacode/Infrastructure/AgentDetection/**` | `components/agent-detection.md` |69 | `supacode/Clients/Notifications/**`, `WorktreeTerminalState+Notifications.swift`, `supacode/Clients/Dock/**` | `components/notifications.md` |70 | `supacode/Features/DiffView/**` | `components/diff-view.md` |71 | `supacode/Clients/Github/**` | `components/github-pull-requests.md` |72 | `supacode/Clients/Updates/**`, `supacode/Features/Updates/**` | `components/updates.md` |73 | view-mode switching (`supacode/Features/App/**`, `ContentView.swift`) | `components/view-modes.md` |7475 `overview.md`, `concepts.md`, and `README.md` only need touch-ups for the76 addition/removal of a **major** feature — leave them alone otherwise.77784. **Verify against the source of truth.** For each doc identified, check its79 falsifiable claims against the authoritative source — not against the diff80 summary — and apply minimal edits per the conservative rules above:8182 | Claim type | Source of truth |83 |------------|-----------------|84 | Keyboard shortcuts (key + modifiers + command ID, remappability) | `supacode/App/AppShortcuts.swift`; menu wiring in `supacode/Commands/*.swift` |85 | Settings field names / types / defaults | `supacode/Features/Settings/Models/GlobalSettings.swift`, `RepositorySettings.swift` |86 | CLI commands / flags / ranges / error codes / JSON fields | `ProwlCLI/**` and `supacode/CLIService/**` (and, if the CLI is installed, `prowl <cmd> --help` for confirmation) |87 | Feature behavior / entry points | the corresponding `supacode/Features/**` or `supacode/Clients/**` |8889 When in doubt whether something is a real, user-facing change, **leave the doc90 as-is and flag it** in the report rather than editing.91925. **Check internal links if files moved.** If you renamed/added/removed any doc93 file, re-run a quick relative-link check so nothing in `docs/` is broken.94956. **Bump the baseline.** Set `last_synced_commit` (and `last_synced_date`, `note`)96 in `docs/.sync-meta.json` to the current `HEAD`. This file is **committed to97 git** so the baseline persists across sessions and machines — never leave it98 uncommitted.991007. **Report.** Output a short summary:101 ```102 ## Docs Sync103 Baseline: <old_hash> → <new_hash>104 Source files changed in range: <count>105106 ### Updated107 - docs/<file> — <one-line what & why>108109 ### Checked, left unchanged (tolerated)110 - <area> — <why it didn't need a doc change>111112 ### Needs human decision (not applied)113 - <large/ambiguous change> — <what & suggested doc action>114 ```115116## Committing117118- **Standalone run:** stage and commit only `docs/**` (which includes119 `docs/.sync-meta.json`); never `git add .`. If anything in `docs/` changed and120 you're not on `main`, open a PR targeting `onevcat/Prowl`.121- **As part of release prep** (the `release` skill, on `main`): commit the doc +122 `docs/.sync-meta.json` changes as **their own commit before the version bump and123 tag** — e.g. `git commit -m "Sync docs for <VERSION>"`. Do **not** leave them124 staged/uncommitted: `release.sh` aborts on a dirty working tree, and the doc125 commit must already be on `main` so it becomes an ancestor of the tag and ships126 inside the release. Bump/tag happen after, never before.127- Always bump and commit `docs/.sync-meta.json` even when no doc edits were128 needed, so the next run starts from a tight diff range. The baseline records the129 commit the docs were verified against (the current HEAD at run time) — for a130 release that is the code being shipped, captured before the later doc/bump/tag131 commits, which is correct (those commits touch no implementation files).
onevcat