zclaw_openfang/docs/superpowers/specs/2026-04-22-wiki-restructure-design.md

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