Skip to content

docs(intake): ground initiatives in owning docs, not session anchors - #244

Merged
ruby-dlee merged 1 commit into
mainfrom
fm/owning-docs-not-anchors
Aug 18, 2026
Merged

docs(intake): ground initiatives in owning docs, not session anchors#244
ruby-dlee merged 1 commit into
mainfrom
fm/owning-docs-not-anchors

Conversation

@ruby-dlee

Copy link
Copy Markdown
Owner

Why

A two-day "Firstmate on Azure" push was worked from SESSION-ANCHOR-2026-08-13.md plus one narrow leaf design doc (docs/azure-worker-runtime.md) as if those were the specification. Four of the five owning docs (azure-pilot, azure-runner, azure-validation, azure-crosscheck, azure-workers, ~140KB total) were never opened. Result: one leaf subsystem got optimized, progress was reported against a far narrower scope than the initiative, and a documented limitation of a single compartment was relayed to the captain as a requirement of the whole system.

The generalizable failure is that a session log describes STATE, not INTENT, and it was read as the spec.

What changed

One block added to section 7 Intake, immediately before "Write the brief per section 11":

  • find the doc that OWNS the subsystem and read it (this repo's docs declare it outright);
  • anchors, checkpoints, handoff notes, completion reports and evidence folders are state, never intent, and resuming from one requires reconciling it against the owning docs;
  • enumerate sibling docs when an initiative spans compartments, and never generalize one compartment's documented limitation to the system;
  • name the owning docs by path in the brief.

The Azure family is listed explicitly since that is the family the failure hit, and azure-worker-runtime.md is marked as the design leaf under azure-workers.md.

The general form of this rule also went into the machine-global agent instructions, so it applies outside this repo too.

Verification

Doc-only change, 6 lines. The behavior tests that read AGENTS.md all pass locally:
fm-ensure-agents-md, operating-fundamentals, fm-update, lavish-repair, fm-captain-item-check, fm-stow-contract.

A two-day Azure initiative was worked from a session anchor plus one leaf
design doc, so four of the five owning docs were never opened and a
documented limitation of one compartment was reported as a system limit.
Intake now requires finding the owning doc, treating anchors and evidence
folders as state rather than intent, enumerating sibling docs when an
initiative spans compartments, and naming the owning docs in the brief.
@ruby-dlee
ruby-dlee merged commit 0e47a7e into main Aug 18, 2026
13 checks passed
@ruby-dlee
ruby-dlee deleted the fm/owning-docs-not-anchors branch August 18, 2026 15:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant