| name | reporting-checkpointing |
| description | Use when signaling done/blocked/failed, reporting artifacts upward, or deciding whether to create a checkpoint before risky or meaningful state transitions. |
Reporting And Checkpointing
Use this skill when you are about to finish, fail, block, or checkpoint meaningful work.
Reporting upward
When signaling done, include artifact pointers that let your parent continue without guessing:
- PR URL or branch
- commit SHA
- store keys
- file paths
- VM/service identifiers when infrastructure is involved
- tests run and their result
- unresolved risks or deferred verification
- whether you remain alive/idle or are stopping after this task
When signaling blocked or failed, include:
- what you tried
- what failed
- what partial work exists
- where the parent should look next
Reporting rule
Do not optimize for a clean-looking signal.
Optimize for handoff quality.
For recursive code work, "done" means your parent can integrate your slice without re-reading the entire repo just to rediscover what changed.
Before you send your final done, do one bounded inbox catch-up. If new parent/child/peer attention arrived after you finished the main task, either handle a small in-scope follow-up immediately or mention it explicitly in your final signal.
For swarm workers, only claim a final inbox catch-up if your runtime/task path actually left you a bounded final pass before exit. Do not imply a universal self-directed catch-up when the swarm runtime completed atomically.
Disposition-aware conclusion
Before fully disengaging, decide post-task state in this order:
- explicit parent disposition (
stay_idle / stop_when_done)
- category default baseline
- final inbox/context override if a concrete reason to remain alive appeared
If you remain alive and idle, make that explicit in your final signal so your parent knows you are available for reuse.
If you stop when done, make sure your final signal contains enough artifact pointers that replacement or follow-up work can resume cleanly.
If ownership changed during execution, make that explicit too:
- child replaced
- slice reclaimed by parent
- work moved to another VM
- original execution path abandoned
Do not leave stale scheduled checks, store keys, or parent expectations pointing at a child that no longer owns the slice.
Checkpointing
Use reef_checkpoint when:
- you reached a meaningful phase boundary
- the current state is expensive to reproduce
- a risky next step could invalidate valuable progress
General guidance:
- lieutenants: checkpoint at real coordination milestones
- agent VMs: checkpoint when the work has expensive or meaningful phases
- swarm workers: usually do not checkpoint unless the task is unusually long-lived or expensive
Coordination with parent
If a parent may need to recover or replace you later, make sure your signal and your checkpoint together are enough to reconstruct the situation.
