02-sops

implementation notes pattern for sub agent dispatches

2026-05-18·sop·status: active

SOP: Implementation-notes pattern for sub-agent dispatches

When to apply

Any sub-agent dispatch where the agent is implementing a SPEC (not just researching). Specifically:

The pattern

Add to the sub-agent dispatch prompt:

Maintain a running implementation-notes file at:
  ~/.claude/state/implementation-notes-<task-slug>.md
  (or in-vault at: ~/rdco-vault/<project>/implementation-notes/<task-slug>.md
   if the artifact warrants permanent record)

Capture as you work:
- **Design decisions**: choices you made where the spec was ambiguous
- **Deviations**: places where you intentionally departed from the spec, and why
- **Tradeoffs**: alternatives you considered and why you picked what you did
- **Open questions**: anything you'd want me (parent agent / founder) to confirm or revise

This file is a side-channel for in-flight reasoning. The summary-line return is the post-hoc verdict; this file is the durable record of how you got there.

Why this matters for RDCO

Our sub-agents already return a single advisor-mode summary line ending with DECISION: surface. That's the post-hoc verdict. The implementation-notes file captures the IN-FLIGHT reasoning the verdict came from — which:

  1. Lets the parent agent audit specific calls rather than re-deriving them. E.g., if a deploy script makes 5 ambiguous tax-code choices, the notes show WHICH choices and WHY. Parent can spot one wrong call without re-running.
  2. Lets founder spot misinterpretations EARLIER in a long-running build. The skill-improvement loop (/self-review → /improve autonomous) gets better signal because the notes file shows where the sub-agent had to invent (not just what it shipped).
  3. Reduces re-dispatch cost when a downstream cycle needs to extend or correct the build. The next session reads the notes file instead of reverse-engineering.

Where it lives

Example dispatch language to fold in

When writing sub-agent prompts that meet the REQUIRED criteria above, append this block verbatim:

IMPLEMENTATION-NOTES REQUIREMENT (per 2026-05-18 SOP):
Maintain a running implementation-notes file at <path>. As you work, capture:
- Design decisions (spec ambiguities resolved)
- Deviations (intentional departures from spec + reasoning)
- Tradeoffs (alternatives considered + why you picked what you did)
- Open questions (parent / founder needs to confirm)

This file is your in-flight reasoning record. The final summary-line return is the verdict; this file is how you got there.

Audit hook (future)

A future check could scan ~/.claude/state/implementation-notes-*.md files on the morning brief and surface any with ## Open questions sections that have no resolution yet. That would close the loop from "sub-agent flags a question" to "founder sees it surface organically."

For now, the parent agent handles surface-to-founder manually when the notes contain meaningful open questions.

Source

Related