docs(spec): wiki 重构设计文档 — 三级结构+集成契约+症状导航
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
iven
241
docs/superpowers/specs/2026-04-22-wiki-restructure-design.md
Normal file
241
docs/superpowers/specs/2026-04-22-wiki-restructure-design.md
Normal file
@@ -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?
|
||||
Reference in New Issue
Block a user