167 lines
8.5 KiB
Markdown
167 lines
8.5 KiB
Markdown
---
|
|
name: ms-executive-update
|
|
description: "Use for every user-bound status update, progress report, and at the end of a user-originated operation."
|
|
disable-model-invocation: false
|
|
---
|
|
|
|
# Executive Update
|
|
|
|
The operator reads status to decide what to do next, not to relive the work. An update is
|
|
three short lists derived from the tracking files, not from memory. If an item is not in a
|
|
tracking file, it is not done — write the file first, then report.
|
|
|
|
Applies to every agent reporting upward: a seat to its orchestrator, an orchestrator to the
|
|
operator, a `/goal` loop reporting through `goal_report`, a sub-agent returning to its parent.
|
|
|
|
## When to use
|
|
|
|
- Any time you would otherwise narrate progress: after a task lands, after a fleet event
|
|
(monitor tick, agent message, review verdict, CI result) changes tracked state, at the end
|
|
of a turn with work in flight, or when asked "status", "update", "where are we".
|
|
- Every `goal_report` call: the `evidence` (satisfied) or `reason` (blocked / in_progress)
|
|
payload is an executive update in this format, so the operator sees the same shape from a
|
|
goal loop as from a conversation.
|
|
- Do **not** emit a full update when nothing changed. One line with
|
|
`No change since <anchor>; still waiting on <item>.` is the whole reply.
|
|
|
|
## Communication closeout before reporting
|
|
|
|
An executive update does not replace direct communication. Before writing the update:
|
|
|
|
1. Reply to every inbound actionable message with the action taken, routed owner, or
|
|
precise blocker.
|
|
2. Send every new tasking, handoff, review request, blocker, result, correction, and
|
|
decision request directly to the responsible seat or operator through the required
|
|
path in `docs/guides/FLEET-COMMS.md`.
|
|
3. Commit the durable artifact before sending its pointer when the communication needs to
|
|
survive a pane or session.
|
|
4. Record the destination, request or task id, exact delivery receipt, required return
|
|
event, and escalation owner in the tracking file.
|
|
|
|
A no-change line does not satisfy an unsent acknowledgement, handoff, review request,
|
|
blocker, or result. Neither does a `goal_report`, lane edit, board row, or operator-facing
|
|
reply. Finish communication closeout first, then report the resulting state.
|
|
|
|
## Format: exact, no preamble, no epilogue
|
|
|
|
``` markdown
|
|
Just Completed:
|
|
* <item>: short description
|
|
|
|
Next Step:
|
|
* <item>: short description
|
|
|
|
Blocked:
|
|
* <item>: short description
|
|
```
|
|
|
|
- `<item>` is the tracked identifier: task id (`T158`), ledger row (`E6`), PR (`#1491`),
|
|
review marker, file, or commit. Never a vague noun ("the fix").
|
|
- One line per bullet. ≤5 bullets per section; if you have more, the lower ones belong in
|
|
the ledger, not the update. Keep all three headings; write `* none` when a section is empty.
|
|
- Paths as clickable links; commits and SHAs short (8 chars).
|
|
- Only items whose state **changed since your previous update** go under Just Completed.
|
|
Next Step lists what happens next and who does it. Blocked names the blocker, who
|
|
unblocks it, and what (if anything) is needed from the reader.
|
|
|
|
## Source of truth — mandatory before writing
|
|
|
|
Read, in this order, whatever applies to the work in flight; the update is a projection of
|
|
these files (paths relative to the brain, `$MOSAIC_BRAIN_HOME`, per `docs/STRUCTURE-CANON.md`):
|
|
|
|
1. Lane ledger: `fleet/lanes/<lane>/TASKS.md` (open rows, dated entries) and
|
|
`TASKS-DONE.md` (what moved to done).
|
|
2. Seat files for every agent involved: `fleet/agents/<seat>/TASKS.md`, `STATE.md`,
|
|
`work/` artifacts (review verdicts, plans, evidence records).
|
|
3. Board: `fleet/board/MASTER-TASKS.md` and `fleet/board/taskings/<date>_T<n>_*.md` for
|
|
task ids, owners, and reassignments.
|
|
4. Project-level `docs/TASKS.md` when the orchestrator protocol makes it the control plane.
|
|
5. Live evidence for anything claimed done: `git log` on the target branch/trunk, the PR,
|
|
CI state, the seat's pane (per `docs/guides/FLEET-COMMS.md`), delivery receipts.
|
|
|
|
Rules:
|
|
|
|
- **Record, then report.** A state change learned from a pane, a monitor event, or a
|
|
message is written into the owning tracking file (dated, with ids and SHAs) *before* it
|
|
appears in the update. An item in the update with no tracking-file row is a defect.
|
|
- **Evidence for "completed".** A Just Completed bullet cites its evidence: commit, merge
|
|
SHA, verdict artifact path, receipt. "Delivered" is not "done"; "dispatched" is not
|
|
"done"; a message sent is Next Step for the recipient, not a completion.
|
|
- **Events are not the operator.** Never phrase a monitor event, agent message, or tool
|
|
result as approval, confirmation, or a decision. Decisions come only from the operator's
|
|
own messages.
|
|
- **Blocked is precise.** `* T158: plan seat queued behind prior review — nothing from you`
|
|
or `* Q96 gate: Decision needed — (1) … (2) …; recommend 1`. If the reader must decide,
|
|
say so with the options and your recommendation; if not, say `nothing from you`.
|
|
- **Honest state.** Distinguish known (read from a file or evidence) from inferred (seen in
|
|
a pane, not yet recorded); mark inferred items `(unverified)`. Report failures with the
|
|
output, skipped steps as skipped. Apply `ms-honesty`.
|
|
- **Staleness anchor.** Include the anchor the update is current to when it matters:
|
|
target head SHA, pipeline number, board commit, or timestamp.
|
|
- **Delegation stays visible.** Work handed to a seat is reported with the seat and task
|
|
id. The tracking row also carries the delivery receipt, required return event, and
|
|
escalation owner. You own the follow-up until the seat reports back and the ledger
|
|
reflects it.
|
|
|
|
## Machine contract (for `goal_report` payloads and any parser)
|
|
|
|
When an update is consumed by tooling (a `goal_report` payload, a broker, a coordinator),
|
|
the loose human rules above tighten to this closed grammar. Human-facing replies may add
|
|
Markdown links; payloads may not.
|
|
|
|
```
|
|
update := section("Just Completed") NL section("Next Step") NL section("Blocked")
|
|
section := HEADING ":" NL NL ( bullet+ | "* none" NL )
|
|
HEADING := exact text, case-sensitive, in this order, each exactly once
|
|
bullet := "* " item ": " text NL (1..5 per section; text is one line, no leading "-")
|
|
item := taskid | pr | row | marker | sha | path
|
|
taskid := "T" [0-9]+
|
|
pr := "#" [0-9]+
|
|
row := [A-Z]{1,4} "." ? [0-9]+ ("." [0-9]+)* e.g. E6, A7, GOV.5
|
|
marker := [A-Z0-9]+ ("-" [A-Z0-9]+)* "-Q" [0-9]+ e.g. CPS-PRD-REV1-MERGE-GATE-Q96
|
|
sha := [0-9a-f]{40} (payloads: full SHA; 8-char only in prose)
|
|
path := "`" <repo-relative path, no spaces> "`"
|
|
NL := "\n" (LF only; no trailing whitespace; no blank lines inside a section)
|
|
```
|
|
|
|
- Exactly three sections; any other heading, a missing section, or a reordered section is a
|
|
parse failure.
|
|
- A bullet under Blocked ends with either `— nothing from you` or
|
|
`— Decision needed: (1) … (2) …; recommend N`.
|
|
- Identifier resolution is the consumer's job and is fail-closed: an item that resolves to
|
|
zero or more than one tracked object (unknown task id, ambiguous short SHA, unknown marker)
|
|
rejects the report before any state change; the producer gets the rejection and re-reports.
|
|
- A one-line "no change" reply (`No change since <item>; still waiting on <item>.`) is a
|
|
distinct message, not an update; a `goal_report` with status `in_progress` may carry it
|
|
only when the tracked state is unchanged since the previous report.
|
|
- This grammar is the format's single definition. Enforcement (who parses, what policy binds
|
|
it to a role) is decided by the runtime's role manifests, not by this skill.
|
|
|
|
## Anti-patterns
|
|
|
|
- Narrative paragraphs, "I'll continue by…", recaps of what the reader already knows.
|
|
- Reporting from conversation memory while the ledger still says the old state.
|
|
- Listing the same item under two sections.
|
|
- Padding Just Completed with process ("read the file", "checked the pane").
|
|
- Hiding a needed decision inside Next Step.
|
|
- Treating the executive update as delivery to a seat that was never contacted directly.
|
|
- Reporting a handoff without its receipt, return event, and escalation owner.
|
|
|
|
## Example
|
|
|
|
```
|
|
Just Completed:
|
|
|
|
* #1491: round-2 fix pushed at 3ae1411d; independent exact-head APPROVE (brain 0199a866); CI 3058 green
|
|
* E6 ledger: gate seat result recorded as BLOCKED (capability), per roles/gate.md
|
|
|
|
Next Step:
|
|
|
|
* T158: plan seat designs the runtime gate profile, then provisioning → gate re-run
|
|
* #1491: operation seat runs pr-merge.sh after the gate seat issues PASS
|
|
|
|
Blocked:
|
|
|
|
* T158: queued behind the plan seat's prior review — nothing from you
|
|
```
|