update-wiki

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.

Adapter Maintenance Boundary

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.

Input from break-loop

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:

• decide whether each candidate is durable knowledge;
• split candidates atomically;
• read indexed wiki pages progressively;
• check semantic duplicates;
• choose target ownership;
• edit the chosen leaf wiki page;
• refresh and validate indexes.

If the break-loop handoff says no durable knowledge should persist, skip wiki edits.

---

Wiki First Rule

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:

• executable rules reused across modules, pages, workflows, or layers
• API / payload / command contracts that remain stable outside one call site
• validation and error behavior that future work must preserve
• design decisions with rationale
• project conventions
• gotchas and common mistakes that are not obvious from code, spec, or plan
• cross-cutting thinking checklists in guides/

Local Business Logic Exclusion

Default to skipping wiki updates for local business logic.

Do not write wiki pages for:

• single-page, single-flow, single-vendor, or single-customer branch rules
• implementation details already obvious from the changed code
• temporary rules that belong in the current spec, plan, PR, or commit message
• compatibility handling that only exists because of one local call site

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:

1. Does the knowledge apply across modules, pages, workflows, or layers?
2. Does it remain true outside the current file or immediate task context?
3. Would skipping the wiki make future developers likely to repeat a bug or miss a hidden constraint?
4. Is wiki a better source of truth than code, spec, plan, PR, or commit message?

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.

---

Agent-Led Update Flow

Do the semantic work yourself. Python scripts are only mechanical helpers.

1. Decide whether there is durable knowledge

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:

• temporary task notes
• one-off debugging history
• local business logic or single-context branch rules
• obvious facts already visible from code
• local compatibility handling tied to one call site
• unverified guesses
• formatting-only or typo-only changes

If nothing should be written, report that conclusion and explain the judgment briefly with an explicit skip reason. Do not force a wiki edit.

2. Split the input into atomic candidates

The work may contain multiple durable ideas. Split them into separate update candidates before choosing targets.

For each candidate, identify:

• the durable rule, decision, or gotcha
• why it matters
• likely owner area
• whether it is implementation guidance, checklist guidance, a contract, or a design decision

Examples:

• "Modal content must expose validate, and list pages must keep pagination local" = two candidates.
• "API errors should include code and message" = one candidate with two fields in one contract.

3. Read existing indexed wiki pages before writing

For each candidate:

1. Read .superpowers/wiki/index.md.
2. Follow relevant child indexes.
3. Read the small set of leaf wiki pages that may already cover the same rule.

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.

4. Check semantic duplicates yourself

If the same meaning already exists:

• do not update any wiki page for that candidate
• tell the user which file already covers it
• quote or summarize the existing matching rule

If the idea is only partially covered:

• update only the missing part
• mention the existing coverage and the delta being added

Do not let a script decide whether an update is needed.

5. Choose target ownership yourself

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:

• This is how to implement safely → a relevant indexed leaf wiki page
• This is what to think about before implementing → an indexed guide/checklist wiki page

Before writing, run a bounded ownership boundary check. Use the cheapest sufficient signals first:

1. the parent index description for the candidate page;
2. the page title and first summary paragraph;
3. the overview section when it is near the top;
4. section headings already visible from excerpts read for duplicate checks.

Only read more of a candidate page when:

• the ownership boundary is still ambiguous;
• the candidate appears partially covered;
• you are about to edit a specific section;
• the page may be large or semantically overloaded.

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:

• Type safety owns TypeScript declarations, generics, import type, props/emits typing, generated component declarations, and type organization.
• API/form payload contracts own submitted, omitted, transformed, or rejected fields; dirty flags; request/response semantics; and save helper behavior.
• Security-sensitive field pages own masked secrets, tokens, passwords, placeholder/sentinel values, and constraints on persistence, logging, or submission.
• "Masked secret display values must not be submitted as real payload values" should prefer an API/form payload or security-sensitive field page, not 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.

6. Check whether the target page is too large

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:

• 250+ lines or 12k+ characters: review whether the page still has one clear owner.
• 500+ lines or 24k+ characters: prefer splitting before appending, unless the page is a single cohesive contract/reference.
• 800+ lines or 40k+ characters: do not append unrelated content; review split boundaries first.

Treat a page as semantically overloaded when:

• it covers multiple unrelated modules, workflows, contracts, or design decisions;
• you cannot summarize its owner in one sentence;
• the new candidate can only be appended to the end instead of fitting an existing section;
• the index summary no longer represents the page's main content.

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.

7. Edit the wiki page directly

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.

8. Refresh and validate the mechanical state

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

---

Content Quality Requirements

Mandatory depth for infra / cross-layer / contract changes

Use deeper code-wiki structure when the update includes any of:

• new or changed command/API signature
• cross-layer request/response contract change
• database schema/migration change
• infra integration: storage, queue, cache, secrets, env wiring

For triggered updates, include these sections in the target wiki page:

1. Scope / Trigger
2. Signatures
3. Contracts
4. Validation & Error Matrix
5. Good/Base/Bad Cases
6. Tests Required
7. Wrong vs Correct

Design Decision

### 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
- ...

Gotcha / Common Mistake

### Common Mistake: <name>

**Symptom**: ...
**Cause**: ...
**Fix**: ...
**Prevention**: ...

---

Mechanical Helper Scripts

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.

Forbidden Shortcuts

Do not:

• run removed one-shot update runners
• let a script decide whether an update is needed
• let a script decide final target ownership
• choose targets by token scores, filename matches, or nearest-match fallback
• append to a broad page as a catch-all when no clear owner exists
• treat type-safety pages as owners for API/form payload or security-sensitive field rules unless the rule is specifically about TypeScript modeling
• treat token scores or filename matches as semantic duplicate checks
• write detailed rules into index.md

---

Quality Checklist

Before finishing the update:

• Did you start from the default of not updating wiki and require durable reusable knowledge before editing?
• Did you exclude local business logic, single-context branch rules, and code-obvious implementation details unless they passed the reuse threshold?
• If you skipped all candidates, did you state an explicit skip reason instead of forcing a wiki edit?
• Did you split multi-point input into atomic candidates?
• Did you read relevant indexed wiki pages before writing?
• Did you skip candidates that are already covered and tell the user where?
• Did you choose target ownership yourself rather than outsourcing it to a script?
• Did you verify the target page's ownership boundary with bounded signals instead of weak keyword overlap?
• Did you avoid nearest-match fallback when no clear owner existed?
• If the candidate concerns API/form payload or security-sensitive fields, did you avoid filing it under type-safety unless it is specifically about TypeScript modeling?
• If the target page is large or overloaded, did you split by ownership instead of chunking?
• Did you ask the user when ownership or split structure was ambiguous?
• Is the content durable and reusable?
• Is the content specific instead of generic?
• Did you explain why, not just what?
• Did you avoid putting detailed rules into index.md?
• If a new leaf wiki page was created, is it referenced by an index?
• Did you refresh the index chain after updating body content?

---

Notes

• Only index.md at the wiki root is mandatory.
• The rest of the directory structure is project-defined.
• Detailed wiki pages should stay separate from entry indexes so the system can load them progressively.
• By default, draft/, archive/, and examples/ directories are ignored by index generation.
• Add more ignored directory names in .superpowers/wiki/.adapter-ignore using one directory name per line.