| name | github-wiki |
| description | Build and maintain a canonical, source-backed GitHub Wiki. Use when a project needs a new Wiki, a complete Wiki refresh, rendered-page verification, or an event-driven process that keeps Wiki content aligned with code, issues, and releases. |
| metadata | {"category":"docs","lanes":["claude","codex"]} |
GitHub Wiki
Build the Wiki as verified product documentation, not marketing copy. Treat merged code and live repository state as truth; label everything else explicitly.
1. Fix the contract
Determine from the request and repository context:
- audience: users, developers, operators, or a mix;
- canonical location: GitHub Wiki alone or an existing documented alternative;
- truth boundary: merged behavior, released behavior, Simulator proof, physical-device proof, and planned work;
- publication scope: draft locally, publish directly, or publish plus repository maintenance changes;
- maintenance model: event-driven updates by default.
Ask only about choices that materially change the result. Use explicit user authorization to publish when already given.
Complete when: the audience, source of truth, publication boundary, and acceptance boundary are unambiguous.
2. Build an evidence ledger
Inspect before writing:
- Read repository instructions and current lifecycle rules.
- Inspect the architecture, entry points, configuration, tests, CI, release setup, and user-visible flows. Prefer a code knowledge graph when available.
- Inspect live GitHub issues, pull requests, releases, default branch, visibility, and Wiki state.
- Record each proposed factual claim with its source and status:
verified, planned, or unknown.
- Resolve conflicts in favor of current code and live GitHub state. Preserve unresolved conflicts as explicit unknowns.
Never present a passing build, Simulator run, or open issue as physical-device, TestFlight, production, or release proof.
Complete when: every product, architecture, privacy, setup, testing, and release claim planned for publication has evidence or an explicit status label.
3. Design the smallest complete page set
Create only pages supported by the project. A mature application usually needs:
- Home
- Getting Started
- User Guide
- Architecture
- Data Flow and Durability
- Privacy
- Development
- Testing and Simulator
- Troubleshooting
- Releases and TestFlight
- Roadmap
- FAQ
- Wiki Maintenance
_Sidebar.md and _Footer.md
Collapse or omit pages with no real content. Add domain pages only when the code or operating model requires them. Keep GitHub Wiki canonical; do not create a mirrored docs/wiki tree.
Complete when: every target audience has a clear path from Home to setup, use, understanding, recovery, and current status without placeholder pages.
4. Author from sources
Write concise Markdown with:
- one H1 per content page;
- relative Wiki links such as
[[Getting Started]];
- exact commands and configuration names verified against the repository;
- diagrams only where relationships are materially clearer than prose;
- links to live issues for unfinished acceptance or roadmap work;
- explicit local, cloud, privacy, retention, and deletion boundaries;
- recovery steps tied to actual failure states;
- a current-status section that separates completed, pending, and planned work.
Do not infer features from intent, naming, mocks, or unmerged work.
Complete when: every page is useful on its own, internally consistent, and traceable to the evidence ledger.
5. Initialize and publish safely
GitHub creates the separate <owner>/<repo>.wiki.git repository only after the first Wiki page exists. If the Wiki is empty:
- Create the initial Home page through the authenticated GitHub UI.
- Clone
<repository-url-without-.git>.wiki.git into a separate working directory.
- Add the complete page set.
- Validate before committing.
- Publish the Wiki as one atomic commit unless an established Wiki history requires another convention.
Keep application changes out of the Wiki repository. Preserve unrelated working-tree changes.
Complete when: the Wiki remote contains the intended atomic commit and the local Wiki checkout is clean and synchronized.
6. Validate source and rendered output
Before publication, verify:
- every internal Wiki link resolves to a page;
- filenames and link slugs agree;
- each content page has one H1;
- code fences and tables are balanced;
- Markdown has no whitespace errors;
- the page inventory matches
_Sidebar.md;
- no stale placeholders or unsupported claims remain.
After publication, open every page on GitHub and visually inspect:
- canonical URL and expected heading;
- sidebar and footer;
- internal navigation;
- tables, code blocks, images, and diagrams;
- narrow or long pages for clipping and broken layout.
Wait for asynchronous diagram rendering before judging it. Repair and republish any failure, then repeat the affected checks.
Complete when: every published page has passed both source validation and rendered GitHub inspection.
7. Install event-driven maintenance
Add a Wiki Maintenance page that maps change types to affected pages. Include at least:
| Change | Review these pages |
|---|
| User flow or setup | Getting Started, User Guide, Troubleshooting, FAQ |
| Architecture or storage | Architecture, Data Flow and Durability, Privacy |
| Testing or acceptance status | Testing and Simulator, Roadmap, Home |
| Release or distribution | Releases and TestFlight, Getting Started, Home |
| Closed roadmap issue | Roadmap and every page named by that issue |
If the application repository lacks an equivalent checkpoint, add the smallest pull-request-template section:
## Wiki impact
Select exactly one:
- [ ] No Wiki update is required.
- [ ] Wiki updated — affected pages and Wiki commit: <!-- list pages and link the Wiki commit -->
Also require concrete verification commands or checks with results. Make repository changes through its normal issue, branch, CI, review, and merge workflow. Add no Wiki automation until missed updates demonstrate that the checkpoint is insufficient.
Complete when: future changes have one visible decision point, one canonical Wiki, and an owner-visible path to update affected pages.
8. Close with live proof
Verify and report:
- Wiki URL, page count, and Wiki commit;
- rendered inspection result;
- maintenance mechanism and merged repository change, if any;
- CI and review result;
- open acceptance work that remains explicitly unfinished;
- repository visibility, default branch, and clean synchronization state when relevant.
Complete when: the reported state matches live GitHub state and no required work is hidden behind vague wording.
