Skip to main content

Methodology

What this page is​

Ratiba is built under the S4U Development Methodology — the lifecycle every Soft4U project follows. The canonical source lives at s4u-methodology/docs/methodology.md (also on Adrian's machine at /Users/soft4u/Development/s4u-methodology/docs/methodology.md); this page records how that methodology has actually played out across Ratiba's first eleven shipped milestones.

Ratiba is the second project to apply S4U end-to-end (after trust-relay-workflow). Eleven milestones (M3 through M12, with M8 folded into M7) have shipped under v2.1+ rules. The mental model is a "garden lifecycle": an idea is planted as a brainstorm, watered through the walkthrough phase, transplanted as a locked plan v3, grown wave-by-wave, and harvested at close-out into a memo + ROADMAP tick + STATE.md update.

The methodology is enforced in this repo by three load-bearing pieces: PoC mode rules (ADR-driven decisions, no mocking by default, test evidence in every response), S4U quality gates (ruff zero, tsc zero, tests green before every commit — three-layer hook defence), and the brainstorm → walkthrough → plan → dispatch → close-out lifecycle (this page).

The lifecycle, in one diagram​

Each stage has a canonical artefact home. Designs live at docs/plans/<date>-<slug>-design.md. Locked plans live at docs/superpowers/plans/<date>-<slug>.md. ADRs live at docs/adr/ADR-NNNN-*.md and are registered in the CLAUDE.md table. Close-out memos live at ~/.claude/projects/-Users-soft4u-Development-ratiba/memory/project_*_landed.md (private project artefacts; see §7 below).

Plan walkthrough phase (v1 → v3)​

Methodology v2.1 §5.6 codified what M3-M5 had practiced informally: every plan goes through a walkthrough phase before Wave 0 dispatches. The walkthrough is a focused Q&A pass between Adrian and the planning agent, framed around a small set of locked questions (typically Q1 through Q5). Each question is structured as lean: <default> plus alternatives: <enumerated options>. Adrian either confirms the lean or overrides it; the resolution is then committed back to the plan as a "Walkthrough changelog (v3 — locked YYYY-MM-DD)" section before Wave 0 ever fires.

This phase has earned its keep on every milestone since M5. It catches the cross-consistency drift that v2.1.2 Check A is designed to surface (e.g., M6's schema-vs-baseline-migration mismatch, M11's shared-interface contract gap). It also forces the plan to commit to its task counts and wave shapes — once v3 locks, the dispatch mechanics are deterministic.

For a worked example, see the Walkthrough changelog section at the top of docs/superpowers/plans/2026-05-06-m12-pilot-readiness.md: five questions, all five default leans confirmed, cross-consistency Checks A-E re-run at v3 lock, then Wave 0 dispatched.

Wave structure conventions​

Once v3 locks, the plan dispatches wave by wave. A wave is a set of tasks with a uniform dispatch shape: either sequential (one task at a time, each reviewed before the next fires) or parallel-marked (‖, multiple subagents fire concurrently against pre-pinned shared interfaces). Wave 0 is always sequential and lands the ADR + ROADMAP + CLAUDE.md edits that everything downstream depends on. Tests must remain green at each wave boundary.

MilestoneTasksWavesNotable shape
M3 Tenant registry104First multi-wave milestone; baseline for the pattern
M4 WhatsApp first slice84First channel milestone; Cloud-API direct (ADR-0008)
M5 Conversation FSM135Largest single milestone; methodology v2.1 emerged from M5 close-out
M6 M-Pesa payments145First 4-way ‖ (Wave 2)
M7 Voice channel114LiveKit + Deepgram + ElevenLabs integration
M9 Admin orchestrator104First frontend milestone (Next.js 14 + NextAuth-Keycloak)
M9+1 Admin polish84xdist-4 cuts CI 18min → 4min (77% reduction)
M10 Tier-2 channels125First 3-way ‖ Wave 2 + 5-way parallelism stress
M11 Tenant self-service145First 5-way ‖ Wave 2 + cross-sell + personality dials
M12 Pilot readiness237First 8-way ‖ Wave 2; surfaced docusaurus-build single-thread amendment

Wave 2 is the canonical "wide parallel" wave across most milestones — the wave where pre-pinned shared interfaces let 3-8 subagents make progress concurrently. The progression from M6's 4-way to M12's 8-way reflects accumulated discipline around interface-pinning at brief time, not a model improvement.

Methodology v2.1.4 amendment candidates​

Approximately fourteen candidate amendments have accumulated across the M9+1, M10, M11, and M12 close-out memos. Per ADR-0011 D10, these are advisory at M12 close-out — they get codified in W6 close-out as a separate s4u-methodology repo PR rather than blocking the milestone close. A representative subset of seven (full set lives in the close-out memos and the upstream PR):

  • Shared-interface contract pinning at parallel-dispatch brief time — every ‖ wave's brief must include the locked interface signatures of any shared modules touched, not just the file paths (M11 + M12 lesson).
  • Docusaurus-build is single-threaded — never dispatch >1 npm-build subagent in parallel; the build process is not concurrency-safe and stalls when contended (M12 W2 stall lesson).
  • Test-from-backend-cwd discipline — pytest must be invoked from /Users/soft4u/Development/ratiba/backend, not from project root; project-root invocation breaks PYTHONPATH resolution (M11 close-out lesson).
  • xdist -n 4 cap for Keycloak-bound tests — higher parallelism saturates Keycloak's admin-realm token cache and produces flake (M9+1 lesson, codified in pytest.ini).
  • LSP-vs-CLI pyright divergence — when LSP shows zero errors and CLI reports issues, the CLI is canonical; LSP caches stale type info across edits (M10 architectural lesson).
  • Watchdog-stall files-on-disk recovery as default plan, not exception — when a subagent stalls past the watchdog deadline, recover from on-disk artefacts rather than restarting the dispatch; this pattern recurred in M6, M7, M11, and M12 (recurring pattern → upgrade to default).
  • Schema-aware ADR ↔ plan ↔ baseline-migration cross-grep at v3 lock — extend v2.1.2 Check A to grep schema names across the three sources and fail v3 lock on divergence (M6 lesson; first applied in M11 walkthrough).

The W6 close-out memo logs the full list. The s4u-methodology PR codifying them — once merged — bumps the methodology version to v2.1.4.

Close-out memos​

Every milestone closes with a memo at ~/.claude/projects/-Users-soft4u-Development-ratiba/memory/project_*_landed.md. The memo captures: a one-paragraph summary, the per-task arc (SHA + 1-line summary per task), 3-5 architectural wins surfaced, the full set of methodology amendment candidates, and a "what M-next inherits" section.

These memos are private project artefacts — they live under Adrian's ~/.claude/projects/ directory because they reference internal plans and SHAs rather than being externally consumable narrative. The links below render as file:// paths and won't resolve for public readers; this is a deliberate limitation per ADR-0011 D10.

The M12 close-out memo will land at W6 alongside the methodology v2.1.4 PR.