Suggest edit — Design History — how this wiki got scaffolded

Title

Name

Note

---
title: Design History — how this wiki got scaffolded
type: meta
visibility: public
---

# Design History

On 2026-04-20, Jacob asked Claude Code to turn the `#explainingideaflow` tag corpus into a coherent LLM wiki. The earlier exchange (line 462 of session `1137ed19-6d0a-4294-9240-7c559603a947`) had already laid out the question:

> "Separately I'm also thinking about somehow integrating all of the `#explainingideaflow` tags from notestream and slack into some LLM wiki which coherently updates the IdeaFlow vision. I'm wondering if it should be in this wiki or a different wiki."

Claude's recommendation at that time (unactioned until now): a **separate wiki**, cross-linked with [vision-convo](https://wikihub.md/@jacobcole/vision-convo). On 2026-04-20, Jacob said "let's try to make a wiki about that and maybe add to it by referencing relevant stuff in the current wiki." This page records how the scaffold was chosen.

## Claude Code's original proposal

1. **Name:** `ideaflow-vision`
2. **Structure:** `index.md`, `AGENTS.md`, `raw/` by year-window, `wiki/framings/` (one page per metaphor), `wiki/pitches/` (audience-specific), `wiki/themes/`, `wiki/sources/`
3. **Privacy:** synthesize *Jacob's own* framings; co-worker quotes sparingly. Cross-link heavily to vision-convo.
4. **Scope:** Slack only for v1. Defer notestream/Thoughtstream.

## Codex second opinion (gpt-5.4 high, 2026-04-20)

Asked Codex to push back. Summary of its critique:

1. **Separate wiki — yes, agreed.** Different source type, different job, different reader intent. Don't bury this inside vision-convo.
2. **"Too axis-heavy."** Don't make framing, audience, theme, and era *all* first-class. Pick a primary axis.
3. **Recommended organization (hybrid):**
   - *Primary:* functional layers — `personal/`, `team/`, `humanity/`
   - *Secondary:* `framings/` — one page per durable metaphor
   - *Single:* `chronology.md` — era as context, not navigation
   - *Single:* `entry-points.md` — audience translations
4. **Quote ratio:** 80–90% synthesis, 10–20% verbatim. Keep `raw/` lightly cleaned.
5. **Missing page types:** `north-star-thesis`, `what-it-is-not`, `system-map`, `chronology`, `canonical-terms`, `open-questions`, `use-cases`.
6. **Rename `pitches/`:** reads salesy and time-bound → `translations/` / `entry-points/` / `explainers/`.
7. **Risks:** context collapse, internal-language leakage, metaphor sprawl, product/worldview blur. Mitigations: editorial note, dating, separate canonical-current from historical, be selective with quotes even with permission.

## Jacob's decisions

1. **Keep `pitches/`.** Overrule Codex's rename. "Pitches" is the right word; the wiki isn't ashamed of pitching.
2. **Use verbatim lines.** Invert Codex's ratio — lean on Jacob's own voice. Synthesis is connective tissue, not the main event.
3. **Evolution, not change.** Frame the chronology this way: *"The vision hasn't necessarily changed longitudinally, but it has been refined and has evolved and matured, and more forks have been discovered, with more details and realizations."* This is the backbone of [[../chronology|chronology.md]].
4. **Adopt** Codex's missing page types: north-star-thesis, what-it-is-not, system-map, canonical-terms, open-questions, use-cases.
5. **Adopt** the functional-layer primary organization (personal → team → humanity).
6. **Save** this design history in the wiki itself (this page) *and* in a beads ticket.

## Risk mitigations adopted

- Editorial note in [[../../AGENTS|AGENTS.md]] acknowledging the synthesis is of historical framings.
- Date every ingested excerpt in `raw/`.
- Every framing page has a `first-used` date and cites the raw source.
- Linking discipline: framings cite [[../north-star-thesis|north-star-thesis]] to avoid metaphor sprawl.
- Separation of concerns: [[../what-it-is-not|what-it-is-not]] and [[../system-map|system-map]] draw the product/philosophy line.

## Related

- Beads ticket: `wikihub-4i3b` (full design history + decisions, on the wikihub issue tracker)
- Session: `1137ed19-6d0a-4294-9240-7c559603a947` — original conversation that raised the question
- Codex session: `019daa5f-4a5c-7771-a654-a07d44510344` — second-opinion conversation
- Sister wiki: [vision-convo](https://wikihub.md/@jacobcole/vision-convo)

## What this page is *for*

When a future editor (Jacob or an agent) looks at this wiki and asks "why this shape and not another?" — the answer is here. The shape is a compromise between a bottom-up archive of Jacob's actual framings and a top-down taxonomy Codex proposed. Both perspectives left their fingerprints.