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

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