From 8fd8c02953588f568a6a317009b1129b52a31550 Mon Sep 17 00:00:00 2001 From: iven Date: Wed, 22 Apr 2026 20:00:39 +0800 Subject: [PATCH] =?UTF-8?q?docs(spec):=20wiki=20=E9=87=8D=E6=9E=84?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3=20=E2=80=94=20=E4=B8=89?= =?UTF-8?q?=E7=BA=A7=E7=BB=93=E6=9E=84+=E9=9B=86=E6=88=90=E5=A5=91?= =?UTF-8?q?=E7=BA=A6+=E7=97=87=E7=8A=B6=E5=AF=BC=E8=88=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 --- .../2026-04-22-wiki-restructure-design.md | 241 ++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-22-wiki-restructure-design.md diff --git a/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md b/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md new file mode 100644 index 0000000..fc8ff24 --- /dev/null +++ b/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md @@ -0,0 +1,241 @@ +# Wiki Restructure Design + +> Date: 2026-04-22 +> Status: Approved +> Author: Claude + User brainstorming session + +## 1. Problem Statement + +Current wiki (16 files, ~155KB) has three structural problems: + +1. **No task-oriented navigation** — Cannot go from symptom to module quickly +2. **Duplicate content** — Middleware/security/evolution described in 3+ pages +3. **Missing integration contracts** — Cross-module boundaries undocumented +4. **Growing append-only sections** — log.md already 31KB, known-issues.md 13KB + +The wiki's primary reader is a Claude AI session that reads it at conversation start to orient itself. Secondary reader is the human developer. + +## 2. Design Principles + +1. **Wiki documents what code cannot tell you** — WHY decisions, navigation shortcuts, traps, invariants +2. **Code logic sections focus on flows + invariants + algorithms** — NOT field lists or function signatures +3. **Page size budget** — index ≤ 120 lines, module pages 100-200 lines (3-6KB) +4. **Single source of truth per topic** — No content duplicated across pages; use references +5. **Append-only sections are capped** — log.md capped at 50 entries, old entries archived + +## 3. Structure + +### 3.1 Level 1: `index.md` — Navigation + Symptom Index + +``` +wiki/index.md +├── Project one-liner +├── Key numbers table (cross-validated with TRUTH.md) +├── System data flow diagram (existing ASCII art) +├── Module navigation tree (one-line description per module) +├── Symptom navigation table (NEW) +└── Module dependency map (who calls who) +``` + +**Symptom Navigation Table** (NEW): + +| Symptom | First check | Then check | Common root cause | +|---------|-------------|------------|-------------------| +| Stream stuck | routing | chat → middleware | Connection lost / SaaS relay timeout | +| Memory not injected | memory | middleware | FTS5 index empty / middleware skipped | +| Hand trigger failed | hands-skills | middleware | Tool call blocked by Guardrail | +| SaaS relay 502 | saas | routing | Token Pool exhausted / Key expired | +| Model switch not working | routing | chat | SaaS whitelist vs local config mismatch | +| Agent creation failed | chat | saas | Permission or persistence issue | +| Pipeline execution stuck | pipeline | middleware | DAG cycle / missing dependency | +| Admin page 403 | saas | security | JWT expired / admin_guard blocked | + +**Target**: ≤ 120 lines. A new AI session reads index and immediately knows which modules to open. + +### 3.2 Level 2: Module Pages (~15) + +Each module page has 5 sections in reading priority order: + +#### Section 1: Design Decisions (WHY) + +- Why this module was designed this way +- Historical context and background +- Trade-offs made and alternatives rejected +- Key architectural decisions + +Format: prose paragraphs + Q&A pairs for important decisions. + +#### Section 2: Key Files + Data Flow (WHERE) + +- Core files table (3-7 files, one-line responsibility each) +- Module-internal data flow diagram (ASCII or mermaid) +- **Integration contracts** (NEW): + - What this module calls upstream + - What this module exposes downstream + - Interface shapes at boundaries + +#### Section 3: Code Logic (LOGIC) + +Focus on three types of information that code alone cannot efficiently convey: + +- **Key data flows**: Cross-function/cross-file complete paths +- **Invariants**: Constraints that must always hold (marked with ⚡) +- **Non-obvious algorithms**: Logic that is hard to understand from reading code alone + +Explicitly EXCLUDED: +- Field lists (read from code) +- Function signatures (read from code) +- CRUD operations (obvious from code) +- Anything that can be answered by `grep` + +#### Section 4: Active Issues + Gotchas (GOTCHAS) + +- Active issues (0-5 items, removed when fixed) +- Historical pitfall records (≤ 10 items, distilled to one lesson each) +- ⚠️ Warnings (error-prone areas) + +#### Section 5: Change Log (CHANGES) + +- Last 5 changes (format: date + one-liner) +- Older changes → global `log.md` + +### 3.3 Module Page Template + +```markdown +--- +title: {Module Name} +updated: {YYYY-MM-DD} +status: active | stable | developing +tags: [{module-specific tags}] +--- + +# {Module Name} + +> From [[index]]. Related: [[related-module-1]] [[related-module-2]] + +## Design Decisions + +{Why this module exists, key design choices, tradeoffs} + +## Key Files + Data Flow + +### Core Files + +| File | Responsibility | +|------|---------------| +| `path/to/file` | One-line description | + +### Data Flow + +``` +{ASCII flow diagram} +``` + +### Integration Contracts + +| Direction | Module | Interface | Notes | +|-----------|--------|-----------|-------| +| Calls → | {module} | {function/API} | {when/why} | +| Called by ← | {module} | {function/API} | {when/why} | + +## Code Logic + +### Key Data Flows + +{Cross-function paths with intent} + +### Invariants + +⚡ {Invariant 1}: {description of what must always be true} + +⚡ {Invariant 2}: {description} + +### Non-obvious Algorithms + +{Algorithms that are hard to understand from reading code} + +## Active Issues + Gotchas + +### Active Issues + +| Issue | Severity | Status | Notes | +|-------|----------|--------|-------| +| {description} | P{0-3} | Open | {context} | + +### Historical Pitfalls + +- {Lesson learned}: {one-line description of what went wrong and the fix} + +### Warnings + +⚠️ {Warning}: {what to watch out for} + +## Change Log + +| Date | Change | +|------|--------| +| {YYYY-MM-DD} | {one-line description} | +``` + +## 4. Migration Plan + +### 4.1 Pages to Create/Update + +| Page | Action | Notes | +|------|--------|-------| +| `index.md` | Restructure | Add symptom table, remove architectural Q&A (move to modules), target ≤ 120 lines | +| `routing.md` | Restructure | Move Store list to respective modules, add integration contracts | +| `chat.md` | Restructure | Add invariants, integration contracts | +| `saas.md` | Restructure | Remove security details (reference security.md), add contracts | +| `butler.md` | Restructure | Add integration contracts with middleware | +| `middleware.md` | Restructure | Become single source of truth for middleware, add contracts | +| `memory.md` | Restructure | Absorb hermes insights, add invariants | +| `hands-skills.md` | Restructure | Add integration contracts | +| `pipeline.md` | Restructure | Add integration contracts | +| `security.md` | Restructure | Own all security design, add contracts | +| `data-model.md` | Restructure | Add integration contracts | +| `feature-map.md` | Convert to index | Distribute chain traces to modules, keep as index | + +### 4.2 Pages to Merge/Archive + +| Page | Action | Destination | +|------|--------|-------------| +| `known-issues.md` | Convert to pointer | Active issues → per-module, global file = links only | +| `log.md` | Cap at 50 entries | Archive old entries to `wiki/archive/log-{YYYY-MM}.md` | +| `hermes-analysis.md` | Archive | Key insights → `memory.md`, file → `wiki/archive/` | +| `development.md` | Keep as-is | Global dev standards, not per-module | + +### 4.3 Duplicate Content Resolution + +| Content | Current Location | New Owner | Others | +|---------|-----------------|-----------|--------| +| Middleware descriptions | middleware + saas + security | `middleware.md` | Reference only | +| Security mechanisms | security + saas | `security.md` | saas.md references | +| Evolution engine | memory + middleware + index | `memory.md` | Others reference | +| Store listing (25) | routing.md | Split: chat→chat, saas→saas, etc. | routing.md keeps connection stores | +| lib/ file listing (75) | routing.md | `development.md` or dedicated reference | routing.md removes | + +## 5. Validation Criteria + +- [ ] New AI session can locate any module's core files from index in ≤ 2 hops +- [ ] Each module page has integration contracts section +- [ ] No content duplicated across ≥ 3 pages +- [ ] index.md ≤ 120 lines +- [ ] Each module page 100-200 lines +- [ ] log.md ≤ 50 active entries +- [ ] Symptom navigation table covers top 8 common debugging scenarios + +## 6. Risks and Mitigations + +| Risk | Likelihood | Impact | Mitigation | +|------|-----------|--------|------------| +| Module pages exceed size budget | Medium | AI context waste | Trim during migration, move details to archive | +| Invariants drift from code | Medium | Misleading docs | Add "last verified" date, check during code changes | +| Integration contracts incomplete | High | Gap remains | Start with existing cross-references, fill during next debug session | +| Migration breaks existing workflow | Low | Confusion | Migrate one module at a time, verify after each | + +## 7. Open Questions + +- Should feature-map.md be fully absorbed into modules or kept as a standalone index? +- What format for integration contracts — prose table or structured schema? +- Should we add a `wiki/templates/module-template.md` for consistency?