with one click
update-wiki
// Review completed implementation, debugging, review, or design work and update .superpowers/wiki/ when durable implementation knowledge should persist for future sessions.
// Review completed implementation, debugging, review, or design work and update .superpowers/wiki/ when durable implementation knowledge should persist for future sessions.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | update-wiki |
| description | Review completed implementation, debugging, review, or design work and update .superpowers/wiki/ when durable implementation knowledge should persist for future sessions. |
Generated by superpower-adapter.
When you learn something valuable from implementation, debugging, review, or discussion, use this skill to decide whether the relevant wiki pages under .superpowers/wiki/ need updates.
Timing: After completing a task, fixing a bug, discovering a new pattern, or making a design decision that future sessions should know.
This skill performs wiki maintenance and durable-knowledge review only. Its local completion proves at most that wiki maintenance ran, indexes were refreshed, mechanical validation was checked, or no durable knowledge needed to persist; it does not prove that implementation, debugging, tests, builds, review, commit readiness, PR readiness, or plan tasks are complete.
Do not invoke Superpowers completion, review, verification, or similar workflow skills solely because update-wiki wrote a wiki page, skipped a wiki edit, refreshed indexes, or ran local wiki validation. If you are about to claim the preceding implementation or bug fix is complete, fixed, passing, or ready, that claim must be verified by the originating Superpowers development workflow; update-wiki does not replace implementation verification.
When invoked after break-loop, treat the break-loop output as post-debugging context and candidate input only.
If the handoff follows a systematic-debugging → break-loop flow, you may reuse the root cause, evidence, failed attempts, final fix, and verification result. Still apply this skill's normal responsibilities:
If the break-loop handoff says no durable knowledge should persist, skip wiki edits.
Wiki content should capture durable implementation knowledge, not generic prose or a summary of the latest code change.
Default to not updating wiki. Only write when the knowledge is durable, reusable, and likely useful outside the immediate code context.
Good wiki updates include engineering knowledge that passes at least one promotion test:
guides/Default to skipping wiki updates for local business logic.
Do not write wiki pages for:
Only promote local-looking knowledge when it represents a stable external/domain constraint, a cross-layer contract, reused project convention, or a repeated gotcha that future sessions are likely to rediscover incorrectly.
Use this reuse threshold before writing:
If the candidate does not pass this threshold, state an explicit skip reason such as: No wiki update: this is local business logic already represented in code/spec, not durable reusable knowledge.
Do not treat index.md files as the main place for detailed rules. Keep detailed content in leaf wiki page files and keep indexes lightweight.
Do the semantic work yourself. Python scripts are only mechanical helpers.
Review the completed work and identify only implementation knowledge that future sessions should reuse outside the immediate code context.
Start from skip. Promote a candidate to wiki only when it passes the reuse threshold above and is better preserved in long-term wiki than in code, spec, plan, PR, or commit message.
Skip the update when the work only produced:
If nothing should be written, report that conclusion and explain the judgment briefly with an explicit skip reason. Do not force a wiki edit.
The work may contain multiple durable ideas. Split them into separate update candidates before choosing targets.
For each candidate, identify:
Examples:
For each candidate:
.superpowers/wiki/index.md.Do not scan the full wiki tree unless the user explicitly asks for a full audit. A wiki page is already covered when an existing indexed file states the same durable rule, even if the wording differs.
You may list indexed leaf candidates mechanically:
python3 __SUPERPOWER_ADAPTER_PLUGIN_ROOT__/scripts/wiki_select_target.py --json
This only lists candidates. It does not choose the target for you.
If the same meaning already exists:
If the idea is only partially covered:
Do not let a script decide whether an update is needed.
Each candidate should update exactly one indexed leaf wiki page unless it genuinely spans unrelated areas. Prefer the most specific indexed leaf that owns the rule. Use broader guide wiki pages only when the candidate is a checklist or thinking prompt.
Use this rule:
Before writing, run a bounded ownership boundary check. Use the cheapest sufficient signals first:
Only read more of a candidate page when:
Do not scan the full wiki tree or read full pages by default just to compensate for unclear ownership. A page owns the candidate only when the durable rule naturally fits the page's explicit owner boundary.
Do not use nearest-match fallback. Weak keyword overlap is not ownership. For example:
type, interface, or payload type appearing in a rule does not automatically make it type-safety knowledge.validation appearing in a page does not mean all validation or submission rules belong there.security, token, or secret appearing near typed payload code does not make the rule type-safety knowledge.Ownership examples:
import type, props/emits typing, generated component declarations, and type organization.type-safety.md, unless the durable rule is specifically about TypeScript modeling.If no indexed leaf page clearly owns the candidate, do not append to the closest-looking page. Create a specific leaf page under the nearest clearly owned directory and reference it from the appropriate index.md, or ask the user when the long-term taxonomy is unclear.
If two or more candidate files are equally plausible and the difference affects long-term wiki organization, ask the user which target should own it instead of guessing.
Before editing the chosen leaf page, check whether it is already mechanically large or semantically overloaded.
Treat a page as mechanically large when it has:
Treat a page as semantically overloaded when:
If the page is overloaded, split by ownership into indexed leaf wiki pages. Do not split by arbitrary chunks or create part-1 / part-2 pages.
Prefer sibling leaf pages in the current directory when splitting a small number of peer owners. Create a topic directory with its own index.md only when the original page has become a collection of stable subtopics, when there are three or more child topics, or when local navigation/overview constraints are needed.
If the existing page may already be referenced elsewhere, prefer keeping the original path as an overview or navigation page unless you have verified and updated the references. If sibling pages vs. a topic directory would affect long-term wiki organization, ask the user which structure should own it.
Update the chosen leaf wiki page with Read and Edit whenever possible.
Keep the existing style of the target file.
Do not force every update into a generic template.
If you create a new leaf wiki page, ensure it is referenced by an appropriate index.md.
Detailed rules belong in leaf wiki pages; indexes should contain navigation and short summaries only.
After editing body content, refresh indexed summaries:
python3 __SUPERPOWER_ADAPTER_PLUGIN_ROOT__/scripts/update-wiki.py
Optionally run the mechanical validator:
python3 __SUPERPOWER_ADAPTER_PLUGIN_ROOT__/scripts/wiki_update_check.py --json
Use deeper code-wiki structure when the update includes any of:
For triggered updates, include these sections in the target wiki page:
### Design Decision: <name>
**Context**: What problem were we solving?
**Options Considered**:
1. ...
2. ...
**Decision**: We chose X because...
**Example**:
```text
...
### Project Convention
```markdown
### Convention: <name>
**What**: ...
**Why**: ...
**Example**:
```text
...
### Contract / Rule Update
```markdown
## Update: <title>
### Why
- ...
### Rules / Contracts
- ...
### Validation / Notes
- ...
### Common Mistake: <name>
**Symptom**: ...
**Cause**: ...
**Fix**: ...
**Prevention**: ...
These scripts are helpers only. They do not replace agent judgment.
| Script | Allowed role |
|---|---|
wiki_select_target.py | List indexed leaf candidates. It must not make the final target decision. |
wiki_apply_update.py | Safely write a simple update after the agent already decided target and content. Complex updates should be edited directly. |
wiki_update_check.py | Validate index/format mechanics. It must not decide whether durable knowledge exists. |
update-wiki.py | Refresh indexed wiki page summaries. |
Do not:
index.mdBefore finishing the update:
index.md?index.md at the wiki root is mandatory.draft/, archive/, and examples/ directories are ignored by index generation..superpowers/wiki/.adapter-ignore using one directory name per line.