Skip to content

Brainstorming Session: Continuous-Learning Knowledge System

Date: 2026-04-18 Facilitator: Creative Intelligence (BMAD Method v6) Session #: 13

Objective

Design a continuous-learning knowledge system for a solo product-owner/developer building Finnest — so the owner stays fluent in what is being built, how it is being built, and how the 21 OTP apps fit together — without losing narrative thread as AI sessions churn and the codebase accretes over the 44-week roadmap.

The question as posed: "Is a wiki the best way?"

Context

  • Solo operator, AI-paired. One human (Gautham) + Claude-assisted sessions with session-bounded memory. No team to distribute knowledge across.
  • Already rich in documentation. finnest-planning/ holds architecture.md (~74KB, 12 parts) + 14 ADRs + 12 prior brainstorms + 9 research docs + 1 PRD
  • sprint plans + stories. finnest/ holds CLAUDE.md + CHANGELOG.md + code with @moduledoc discipline.
  • Split-repo topology. Planning in MMGS-Softnet-Pty-Ltd/finnest-planning (private), code in MMGS-Softnet-Pty-Ltd/finnest. These are intentionally separate — planning history travels with decisions; code with implementation.
  • Workflow is BMAD. Slash-commands (/first-in, /last-out, /warren, /moons-spawn, /convergence, /dev-story) already encode knowledge rituals. State lives in _bmad-output/bmm-workflow-status.yaml + sprint-status.yaml.
  • IRAP on the horizon. Phase 0 → 1 lands in production. Auditors will read "how it was built" artifacts in ~12 months. Decision provenance matters.
  • Scale pressure. 19 modules × ~365 features × 44 weeks. No human memory holds this; neither does any single Claude session. The question isn't whether to systematize — it's how.

Desired Outcome

Ranked recommendation: wiki vs. alternatives, with a concrete rollout sequence that respects solo-operator overhead budget (90 minutes to MVP is the target).

Techniques Used

  1. Mind Mapping — surface the full landscape of learning-system options
  2. SCAMPER — transform the existing planning-repo artifacts rather than add parallel stores
  3. SWOT — evaluate the top 4–5 candidate approaches honestly

Ideas Generated

Technique 1 — Mind Mapping: Landscape

Central node: Continuous-learning system for Finnest

Branch A — Prose-based knowledge stores - Wiki (Confluence, Notion, GitBook, BookStack) - Markdown-in-git doc site (Docusaurus, MkDocs-Material, Hugo, mdBook) - Obsidian vault (local knowledge graph, backlinks, graph view) - Personal dev journal (daily-notes, plain markdown) - Roam/Logseq (outliner-style, block references)

Branch B — Structured artifacts (already exist, can be amplified) - ADRs (decision log — 14 and counting) - architecture.md + 4 companions (agents/irap/data/mobile) - PRDs (Scout+Verify complete; 5 more scheduled) - Sprint stories + retros - CHANGELOG.md per repo - CLAUDE.md per repo - @moduledoc / @doc in code - BMAD workflow YAML state (sprint-status, bmm-workflow-status)

Branch C — Live-generated views (built from source, never drift) - ExDoc (Elixir module/function reference — one mix docs away) - mix xref graph visualisation (dep graph across the 21 apps) - Boundary violation report (architecture contract proof) - C4 / Mermaid diagrams auto-rendered from markdown - Phoenix route inventory (mix phx.routes rendered) - Test coverage heatmap (mix test --cover output) - Credo / Dialyzer / Sobelow health dashboard - Oban job catalogue (auto-discovered)

Branch D — Narrative / temporal layers - Weekly "State of Finnest" digest (AI-authored from git log + sprint diff + merged PRs + new ADRs) - Monthly architecture snapshot (delta against previous) - Sprint retrospectives as learning artefacts (Blue Hat reflections) - Video/Loom walkthroughs per domain (5-min each) - Commit messages as first-class memory (Conventional Commits already enforced) - PR descriptions as "why this change" (linked to ADR/story) - Decision-gate recaps (Week-2 gate, Phase-0 gate, etc.)

Branch E — Interactive / on-demand - claude + memory + repo context (already partially live) - RAG "ask my codebase" agent over planning + code - /warren <domain> for focused domain briefings (already exists) - /first-in morning context load (already exists) - /whats-new <since> — new slash-command surfacing recent changes - Spaced-repetition flashcards (Anki) on the 365-feature inventory - Auto-generated quiz on module boundaries (test your own knowledge)

Branch F — Dashboards / at-a-glance - BMAD workflow status board (already in YAML — needs rendering) - Sprint velocity + burndown + points-shipped trend - CI health (build, test, coverage, credo, sobelow, dialyzer) - Module inventory heatmap (tier, state, test coverage, last-touched) - Feature inventory state (P0-P5 completion against 365 features) - IRAP guardrail compliance tracker - Event store catalogue + hash-chain health

Branch G — External / social - Public blog posts (forcing function — explaining to strangers cements learning) - GitHub Discussions (future-team scaffolding) - Conference talks / community shares (high-cost, high-clarity) - Tweet-sized "today I learned" log

Total raw ideas from mind-mapping: ~55 distinct options.

Technique 2 — SCAMPER: Transform what already exists

Rather than inventing a new store, ask what we can do with the artefacts already in play.

Substitute Replace the mental model of "wiki pages you have to remember to update" with auto-generated views that read from source-of-truth files (sprint-status.yaml, ADRs, @moduledoc, CHANGELOG). Wiki entries drift; views rebuilt on every merge don't.

Combine Merge architecture.md + BMAD YAML + CHANGELOG + ExDoc + ADRs into one rendered doc site where each is a section but the render is always current. One URL, always fresh, zero-maintenance per edit (you edit the source; the site rebuilds).

Adapt The /warren skill already loads focused domain context for an AI session. Adapt the same primitive into human-facing output: /warren-brief <domain> produces a 1-page markdown brief suitable for reading over coffee. Adapt /first-in's session-start ritual into a /daily-digest that runs every morning and writes to a dev-journal file.

Modify Enhance each ADR with a trailing "Learning notes" section — not just what was decided, but what the decision taught about the system. Modify CHANGELOG entries to carry #module-tags so learning is indexed by domain. Modify PR template to require an ADR or story link (already partial).

Put to other uses The 12 existing brainstorms are currently write-once-read-maybe. Re-frame them as teaching artefacts — link them from the doc site under each module as "the story of how we got here." They're probably the richest explanation of why the system looks the way it does.

Eliminate Do NOT stand up a separate wiki system (Confluence/Notion) if git+markdown already covers it. Eliminate duplicate stores. One source of truth per fact. Eliminate the temptation to write new docs when the old ones just need surfacing.

Reverse Instead of building "docs that explain the system," build the system that explains itself: every OTP app publishes a README that's mandatory on merge; every public module has @moduledoc; ExDoc renders the whole thing; modules that can't explain themselves fail CI. The code becomes the wiki.

Technique 3 — SWOT: The five leading candidates

Candidate A — Traditional hosted wiki (Confluence / Notion / GitBook)
Strengths Rich WYSIWYG editing; full-text search; mobile-friendly; familiar to future hires
Weaknesses Separate from code → drift is inevitable; subscription cost; context-switch out of terminal; lock-in; requires remembering to update
Opportunities Meeting notes / onboarding when team grows (not now)
Threats Becomes "the place information goes to die" for solo + AI-paced workflow. This is the dominant failure mode for this class of tool in a solo context.

Candidate B — Markdown-in-git rendered doc site (MkDocs-Material / Docusaurus)
Strengths Versioned alongside source; zero drift (source IS the doc); free; renders beautifully; works offline; GitHub Pages / Cloudflare Pages free hosting; Mermaid + PlantUML built in
Weaknesses Initial config (90 min); requires CI pipeline; diagrams need discipline
Opportunities Pulls from both repos (planning + code); auto-rebuilds on every merge; integrates ExDoc as a subsection; IRAP-friendly (audit trail = git log)
Threats Without a "what's new" narrative layer, it stays a reference — not a learning surface

Candidate C — Obsidian vault pointed at the existing planning repo
Strengths Free; local-first; zero migration (planning repo is already markdown); instant graph view + backlinks; fast reading; preserves muscle memory (files on disk)
Weaknesses Not easily shareable (future team); solo-optimised; doesn't render publicly
Opportunities Read-only tool on top of the canonical store. Doesn't add maintenance burden — Obsidian is just a reader
Threats Risk of becoming a personal silo if edits happen in Obsidian-specific formats (block refs, embeds) that break the markdown

Candidate D — AI-authored weekly "State of Finnest" digest
Strengths Zero-drift (reads from sprint-status.yaml + git log + merged PRs + new ADRs); narrative form (most digestible); tunable to the learner; low per-week cost
Weaknesses Requires AI budget + scheduling (cron or manual); quality depends on prompt discipline
Opportunities Writes directly into the doc site; doubles as IRAP evidence ("the story of what we built, week by week"); template reusable for monthly/phase recaps
Threats If it becomes noise it gets ignored. Must be one page, ~5-min read, same day every week

Candidate E — ExDoc + in-code documentation discipline
Strengths Source-of-truth IS the code; no drift possible; Elixir ecosystem first-class; searchable; fast
Weaknesses Covers only code-level "how" — architecture/PRD/rationale sit elsewhere
Opportunities Hook into the doc site as an embedded subsection; fail CI on missing @moduledoc for public modules; pairs perfectly with B
Threats Not sufficient alone — needs a narrative + decision layer on top

Key Insights

Insight 1 — Don't build a wiki. The drift tax is fatal for solo operators.

Source: Mind Mapping (Branch A eliminated), SCAMPER (Eliminate), SWOT (Candidate A).

Impact: High. Effort saved: ~4–8 hours of setup, ~1 hr/week of maintenance-or-guilt.

Why it matters: A separate wiki demands dual-writes — every architecture change means updating the code, the planning doc, and the wiki. Solo + AI-paced workflows drop the third write first. The failure mode of "wiki says X but code does Y" is worse than "no wiki" because it erodes trust in the system. The wiki becomes a pretty lie.

Insight 2 — You already have a wiki. It's the finnest-planning/ repo.

Source: SCAMPER (Substitute, Combine), SWOT (Candidates B, C).

Impact: High. Unlocks everything else.

Why it matters: ~74KB architecture.md + 14 ADRs + 12 brainstorms + 9 research docs + 1 PRD is more documentation than 95% of startups have at any stage, let alone pre-GA. The scarce resource isn't creation — it's consumption. Reframe the problem from "where do I write things down" to "how do I surface what's already written."

Insight 3 — Render, don't re-author.

Source: SCAMPER (Combine), SWOT (Candidate B).

Impact: High. Effort: ~90 min MVP, ~2 hrs polished.

Why it matters: A Docusaurus or MkDocs-Material site that renders the planning repo + the code's CLAUDE.md + CHANGELOG + ExDoc gives you a single URL that is always current because it builds from source on every merge. This is the highest-leverage single intervention. No new content required — you're just rendering what you already have.

Insight 4 — Add a narrative layer via weekly AI-authored digest.

Source: Mind Mapping (Branch D), SCAMPER (Adapt), SWOT (Candidate D).

Impact: Medium-High. Effort: ~30 min prompt design, ~2 min/week to run.

Why it matters: Reference docs answer "what does module X do?" A weekly digest answers "what changed in the last 7 days, and why should I care?" That second question is the one that keeps a solo PO oriented. A 1-page Claude-authored prose summary, scheduled Monday morning, sits next to the first coffee. Narrative beats index for retention.

Insight 5 — Use Obsidian as a reader, not a writer.

Source: SWOT (Candidate C).

Impact: Medium. Effort: ~5 min (open vault, point at planning repo).

Why it matters: The planning repo is already 100% markdown. Obsidian opens it as a vault and instantly gives you backlinks, tag search, and a graph view — zero migration, zero maintenance overhead. Don't author Obsidian-specific syntax (embeds, block refs) that breaks the markdown for other readers. Use it for reading: graph → click around → discover connections you forgot existed.

Insight 6 — Force-functions via CI gates beat discipline.

Source: SCAMPER (Reverse), SWOT (Candidate E).

Impact: Medium. Effort: ~2 hrs (add credo/custom check for moduledocs).

Why it matters: "I'll document it later" fails for everyone, solo operators most of all. CI gates that refuse to merge public modules without @moduledoc, or PRs without an ADR/story reference, convert intention into structure. Pair with the doc site so the reward for good documentation is that it renders beautifully the moment you push.

Insight 7 — Time-box the ritual; don't rely on curiosity.

Source: Mind Mapping (Branch E), existing /first-in ritual.

Impact: Medium. Effort: 0 net (replaces ad-hoc rediscovery time).

Why it matters: 20 min/day (/first-in-driven) or 1 hour/week (Monday-morning digest + Obsidian graph walk) on structured context-load beats 4 hours/week of ad-hoc rediscovery. Durable retention requires repeated, spaced exposure — which the human won't do on curiosity alone. Ritualise it.

Three layers, rollout in priority order:

┌─────────────────────────────────────────────────────────────┐
│  Layer 3: Narrative      Weekly "State of Finnest" digest   │
│                          (AI-authored, 1-page, Monday AM)   │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: Rendered       MkDocs-Material site                │
│                          • finnest-planning/* (ADRs, archi,  │
│                            brainstorms, PRDs, stories)       │
│                          • finnest/CLAUDE.md, CHANGELOG      │
│                          • ExDoc subsection (code API)       │
│                          • CI-built on every merge           │
├─────────────────────────────────────────────────────────────┤
│  Layer 1: Canonical      finnest-planning/ + finnest/ repos  │
│                          (already exist — source of truth)   │
└─────────────────────────────────────────────────────────────┘

         Personal reading tool (optional, zero-overhead):
         Obsidian vault pointed at finnest-planning/

Force-functions: - CI gate: public modules without @moduledoc fail build (added in Phase 0 tail) - PR template: "Which ADR or story does this implement?" (already partial) - ADR template: trailing "Learning notes" section (modify existing template)

Rollout Sequence (respects 90-min MVP budget)

Now (Sprint 2, ~90 min total)

  • Stand up MkDocs-Material site on top of finnest-planning/.
  • pip install mkdocs-material (or Docker equivalent given no-local-Elixir rule)
  • mkdocs.yml with nav pulling architecture.md + ADRs + brainstorms + PRDs
  • GitHub Pages deploy on push
  • Time-box: 90 min. If it's taking longer, the config is wrong; start simpler.
  • Open Obsidian on the planning repo. Zero-config. 5 minutes.

Week 2 (Sprint 2 tail, ~30 min)

  • Extend the doc site to also pull finnest/CLAUDE.md and CHANGELOG.md via a submodule or a small CI script that copies them during build.

Week 3 (Sprint 3, ~60 min)

  • Add ExDoc subsection. mix docs output published at /api/ subpath of the site. Hook into Sprint 3's CI pipeline.
  • Write the weekly digest prompt. Template: read git log --since=7.days
  • diff sprint-status.yaml + list new ADRs/merged PRs → 1-page prose. Save to finnest-planning/digests/YYYY-WW.md. Publish to doc site.

Week 4+ (Sprint 4 onwards)

  • CI gate on @moduledoc. Credo custom check or a small mix task run in the ci-finnest.yml workflow.
  • ADR template v2 with "Learning notes" trailing section. Apply retroactively to the 14 existing ADRs only if prompted by future sessions; don't backfill eagerly.

Deferred (not before Phase 2, when team > 1)

  • Revisit hosted wiki. If/when team grows, the tradeoffs change. Today: no.
  • Public blog posts. Only if marketing strategy requires it.

Statistics

  • Total ideas generated: ~55 (from mind-mapping) + SCAMPER's 7 transforms + SWOT's 5 candidates
  • Categories: 7 branches (prose stores, structured artefacts, live-generated views, narrative/temporal, interactive, dashboards, external)
  • Key insights: 7
  • Techniques applied: 3 (Mind Mapping, SCAMPER, SWOT)
  • Recommended candidates: B + D + C (doc site + weekly digest + Obsidian reader), with E (ExDoc) as a subsection of B
  • Rejected outright: A (hosted wiki)
  1. Stand up MkDocs-Material site as the 90-min MVP (Insight 3). This is the highest-leverage single move.
  2. Open Obsidian on the planning repo (Insight 5). 5-minute setup, immediate payback.
  3. Design the weekly digest prompt in Sprint 3 (Insight 4). Consider pairing with /last-out so the digest writes itself as a by-product of the Friday close.
  4. Add a trailing "Learning notes" section to the ADR template (Insight 2) — modify finnest-planning/adrs/TEMPLATE.md.
  5. Defer the CI gate on @moduledoc to Sprint 4 or later — it's valuable but not yet blocking.

/tech-spec — if any of the above recommendations cross into implementation work that needs scoping (the MkDocs deploy pipeline, the weekly digest agent, the CI gate). The MkDocs site in particular is trivial enough to skip a tech-spec, but the weekly-digest agent is worth one.

Alternatively /architecture — if you want to formalise "Layer 3: Docs" as an architecture component with its own ADR (e.g., adr-015-F-docs-as-code).

Generated by BMAD Method v6 — Creative Intelligence Session duration: ~30 minutes Brainstorm #13