catgo-campaign-conventions — how to author campaign markdown

TL;DR: Progressive md (TL;DR-first, drill down), a README+INDEX pair at every level kept current, log every intervention to LESSONS, human-readable names (no hashes), and a top→stage→calc progressive plan. These keep the tree navigable + resumable from disk.

Progressive markdown

Every md opens with # title + a > **TL;DR:** line, details below in greppable sections. Read INDEX.md first; drill into a branch only when you work it. Keep STATUS.md / LESSONS.md curated, not append-only logs. Don't pile everything into one big md — split by concern, stitch with INDEX.

README + INDEX pair (kept current)

Every level has a README (description) + INDEX (pointer/navigation).

• When you add a stage or calc folder, update the parent INDEX.md (one line + role). INDEX is the navigation spine — an empty/stale INDEX breaks drill-down.
• Fill the scaffold's stub files — top README.md (what / goal / current stage), plan.md, cluster.md. Never leave the <...> placeholders the scaffolder writes.
• README (human: what the project is) vs CLAUDE.md (agent bootstrap) vs INDEX (pointer) — distinct roles, don't duplicate.

Log every intervention

Any time you cancel / rebuild / retry a calc, change its inputs, or hit a gotcha, record what changed and why in that calc's LESSONS.md (and the project LESSONS.md if it generalizes). STATUS.md only holds the CURRENT job — it does not remember a prior cancelled/failed attempt, so the history lives in LESSONS. (catgo campaign submit updates STATUS.md automatically; LESSONS is on you.)

Human-readable names (never hashes)

Names are readable; uniqueness comes from the project/stage/calc path hierarchy. A clash gets a readable -2 suffix, never a digest. The remote work_dir mirrors the local tree.

Progressive plan (top → stage → calc)

• Top plan.md = only WHAT (goal + the stage list, each line LINKING to that stage's plan).
• calc/<stage>/plan.md = mid-level detail + links to its calcs.
• calc/<stage>/<calc>/plan.md = the FULL recipe (method, params + rationale, convergence, freq/restart strategy, result to extract, dependencies). Keep the top short; push specifics down. (Flat campaign with no stages → two levels suffice.)