After the 3-cycle slice arc (144-146) closed soc-y5vh.5 and exposed
3 production adapters via the CLI, the cycle-shape itself became
durable IP. This learning captures the template so future cycles
can replicate it for any production adapter without re-discovering
the pattern.
Key content:
- The 3 cycles in numbers (8-10 min wall-clock, ~250-335 LOC, 4-6
tests each). Variation comes from adapter-side complexity.
- The full cobra/options template (parent noun + verb subcommand +
injectable function field + line-delimited JSON output).
- 5 'why this shape works' principles (cobra noun-verb, injectable
fn for tests, JSON line-delimited for shell composability, error
wrapping, live-smoke verification).
- 3 anti-patterns observed (name collisions in cli/cmd/ao,
shadowing Go builtins, dead imports — all caught by go vet).
- What this unblocks: any of the 14 production adapters can now be
CLI-exposed in ~10 min using this template.
Updated docs/learnings/README.md catalog to surface the new
learning. Catalog now has 7 entries; the cli-wiring entry pairs
with cycle-122's wire-up-arc and cycle-127's substring-sed-overreach
as the 3 BC-ports-arc-derived rules.
Why this learning matters:
- The remaining BC ports (Citation, Operator, Harness,
ClaimEvidenceBinder, GateRunner, FactoryAdmission, ClaimEvidence,
EventBus, etc.) lacking CLI exposure are now cheap to add — the
template removes design overhead.
- skills/evolve/SKILL.md Step 0/1.5 callers (soc-y5vh.1, .2)
can consult this learning when wiring the new shell-outs.
- Future operator who wants to expose a new adapter doesn't have
to re-derive the parent-noun + verb-subcommand + injectable-fn
decision space.
Companion to cycle-122 wire-up-arc learning. Same arc shipped a
durable code surface AND now a durable how-to surface.
Cycle 147 / soc-y5vh.5 retrospective-learning mode.
docs/learnings/ contained 6 files but no index. The 3 new 2026-05-13
learnings (wire-up arc, substring-sed-overreach, /loop context drift)
joined 3 prior files without any cross-referencing surface for
operators browsing the directory.
New file: docs/learnings/README.md.
Contents:
- Catalog table of all 6 current learnings, chronological newest-
first, with one-line takeaway per row. Each row links the file.
- "When to add a learning here" rubric — 3 positive triggers (long
arc with non-obvious lessons; mistake-derived rule; empirical
observation refining theoretical concern) and 3 negatives (one-
off bug fixes, canonical-contract material, status updates).
Maps directly to the 2026-05-13 trio shapes.
- File shape template: frontmatter required (title, date, tags,
source, optional companion), body shape suggested but not
rigid.
Why this helps:
- Future cycle reading docs/learnings/ sees the inventory at a
glance instead of clicking through 6 files.
- "When to add" prevents future cycles from confusing one-off bug
fixes (commit message suffices) with capture-worthy learnings.
- Frontmatter convention is now documented so `ao lookup` and
future indexers can rank consistently.
This is the docs-side complement to cycle 133's bd-side annotations:
both cycles add discoverability infrastructure around work that
already shipped. Discoverability compounds — future cycles save
time by not re-finding what's already known.
Cycle 134 / docs-learnings-index mode.
Boden Fuller