aar-followthrough

Files (1)

• SKILL.md

SKILL.md (first lines)

---
name: aar-followthrough
description: "Run AFTER [aar] completes to elaborate and plan every §7 recommendation into an owned, verifiable goal that feeds into [goal-selection]. Use whenever the operator says 'elaborate on and plan for all recommendations', 'plan the recommendations', 'follow through on the AAR', 'turn the AAR recommendations into plans', 'what do we do with these recommendations', or 'make the AAR recommendations actionable'. This is the bridge between AAR (what we learned) and goal-selection (what we do next) — it closes the retrospective→prospective loop so recommendations do not rot."
version: 0.4.1
execution-mode: side_effecting
argument-hint: "[<aar-name-or-path>] [--no-seed] [--no-bus]"
category: fleet-ops
status: candidate
---

> **Finalize shortcut**: After the skill produces a seed file, run
> `aar-followthrough-finalize <seed-file.json>` to post the SITREP and
> ingest the seed in one command. Add `--dry-run` to review without
> posting. The wrapper guards against re-ingesting already-processed
> seed files (status=ingested/superseded/declined).

# AAR Follow-Through

Turn the §7 Recommendations of a completed AAR into owned, verifiable, executable plans — then hand them to `[goal-selection]` as a seed file so the fleet can actually do them.

## Why this skill exists

An AAR ends with a prioritized one-liner list:

```
1. [HIGH] <action> -- addresses: <which improve>
2. [MED]  <action> -- addresses: <which improve>
```

Each line is an **intention**, not an action. Intentions rot. Without a follow-through step, §7 becomes a graveyard of good ideas: no owner, no deadline, no verification, no path into the work-selection system. This skill is the anti-rot step. It does two things to every recommendation:

- **Elaborate** — expand the one-liner into real understanding: what it means, the mechanism, the scope, and *why* it matters traced back through §6 (the Improve it addresses) to §4 (the root cause). Elaboration frequently surfaces recommendations that are vague once expanded, that conflict with each other, or that have hidden ordering dependencies — all invisible at one-line resolution.
- **Plan** — convert the elaborated intention into a goal-shaped, owned, verifiable plan that `[goal-selection]` can ingest as a candidate goal.

The output is prospective, so the bus vehicle is a **SITREP** (forward-looking), not another AAR. See the AAR-vs-SITREP table in `[aar]`: AAR is "what did we learn", SITREP is "what do we do next". This skill lives on the SITREP side.

## When to run

- Immediately after `[aar]` completes, when the operator says "elaborate on and plan for all recommendations" or any variant.
- Any time the operator points at an existing AAR and asks to make its recommendations actionable.
- Do NOT run without an AAR in hand (this session's output, or a path). If no AAR can be located, stop and say so — there is nothing to follow through on.

## Inputs

- **Primary**: the AAR's §7 Recommendations (the one-liner list).
- **Trace context**: §6 Improves (what each recommendation addresses) and §4 Root Causes (the why behind the Improve). The elaboration is only as good as this trace — a recommendation detached from its root cause becomes a surface fix.
- **Optional**: §1 Mission & Intent (keeps plans aligned with what the operation was originally trying to do).

Locate the AAR from, in order: (1) an explicit path/name argument, (2) the most recent AAR produced in the current session, (3) a path the operator provides when asked. Do not fabricate an AAR's contents — if you can only see part of it, say so and ask.

## Workflow

### 0. **[MANDATORY]** Emit SKILL_INVOKE

Post SKILL_INVOKE to the bus before any stateful action (writing the seed file, posting the SITREP). Use the canonical sender identity for the current runtime; do not invent one.

```
Type: SKILL_INVOKE
To: all
Message: [skill=aar-followthrough] [mode=side_effecting] [args_hash=<sha256>] [session=<session_id>]
```

Delegate the actual bus write to `[bus]` rather than appending to `messages.tsv` directly — this keeps the skill portable across platforms and avoids re-implementing the host-tag-first validation that `[aar]` and `[bus]` already enforce.

### 1. Locate and parse the AAR

Read the AAR. **Before extracting numbered sections**, scan the top of the document (above §1) for any corrective addendum, supersession note, or reclassification block — typically blockquoted or bold-labeled "Corrective disposition" text that reclassifies the original outcome (e.g., PASS → PARTIAL / NONCONFORMING), changes which artifacts are canonical, holds implementation pending, corrects eligibility/alias facts, or supersedes the AAR's own §3 claims. If present:

- Record its binding assertions (disposition change, held items, canonical-path corrections, eligibility corrections, alias resolutions).
- Treat the addendum as the governing reality for every recommendation — the original §3/§7 text is historical; the addendum supersedes it.
- In each per-recommendation block (step 3), note whether the addendum affects that recommendation's scope, urgency, or whether it should be held pending. A recommendation the addendum leaves untouched still gets a "addendum does not address this" note so the check is explicit, not silent.

Then extract:
- §7 Recommendations → the work list (each item has a priority tag `[HIGH]|[MED]|[LOW]`, an action, and an "addresses:" pointer to an Improve).
- §6 Improves → the failure each recommendation is supposed to fix.
- §4 Root Causes → the why behind each Improve.
- The AAR's `operation` name and timestamp → used in the SITREP and the seed filename.

### 2. Cross-check for orphan Improves

Compare §6 Improves against the "addresses:" pointers in §7. If any Improve has **no** recommendation targeting it, surface it explicitly as an orphan:

```
ORPHAN IMPROVES (no recommendation addresses these — consider adding one):
- <improve text> -- evidence: <receipt>
```

This matters because an Improve with no recommendation is a known failure mode the AAR explicitly named but did not act on. Surfacing it forces a decision: add a recommendation, or consciously accept the gap. Either is fine; silence is not.

### 3. Elaborate + plan each recommendation

**Zero-recommendation case**: if §7 has 0 recommendations (empty, "(none)", or absent), skip steps 3-4's per-item loop. Still run the orphan-Improve check (step 2) — an AAR with 0 recs but ≥1 §6 Improve is itself a finding. Write a seed file with `goals: []` and `escalated: []` (empty but present, with lifecycle metadata). Draft the SITREP with `0 plans from 0 recommendations` and **omit the `top:` field** — there is no top goal line when there are 0 plans. Declare PASS only if orphan Improves were flagged; declare PARTIAL if orphans exist and were not surfaced. Do not crash or emit an undefined `top:` field.

For each §7 item, produce one block using the template below. The block is the unit of work — every recommendation gets one, no skipping. If a recommendation is too vague to plan, say so in the elaboration and propose either a sharpened version or a split into smaller plans. Vagueness is a finding, not a reason to skip.

If a §7 recommendation does not trace to any §6 Improve (e.g. a bonus finding, a runbook open item resolved as a side effect), plan it anyway — it is still a stated intention that will rot without an owner. In the "Addresses" field, write `N/A — no §6 Improve trace` and explain what the recommendation actually addresses (e.g. "runbook open item #2, resolved as a bonus output of the validation run"). Flag the count in the run header as `NON-IMPROVE RECOMMENDATIONS: <N>` so the operator can route these separately from the retro→prospect loop at ingest time. Do not exclude non-improve recs from the seed file — exclusion is silent loss, which is the failure mode this skill exists to prevent.

If a recommendation is **self-contradictory where the contradiction reverses intent** (e.g. a headline says "do X" and a note says "consider not-X"), do NOT pick a side. Surface both readings in the elaboration, produce a candidate goal line for each, mark each `DEVIATION-FROM-ORIGINAL-INTENT: operator-decision-required`, and escalate to the operator before writing either into the seed file. Reversing a recommendation's intent is a decision that belongs to the operator or AAR author, not to this skill.

If a recommendation is a **"consider whether …" question rather than an action**, do NOT answer the question by planning one branch. Surface the question, enumerate the candidate actions that would resolve it either way, and escalate to the operator to pick. A question is not a recommendation; planning it as if it were silently closes a decision the AAR author left open.

### 4. Build the goal-harness seed file

Collect every plan's goal line + details + priority into a JSON file in the exact schema `goal-harness.py seed` expects (verified against `$HOME/.agents/scripts/goal-harness.py`). Include lifecycle metadata so the seed file is a traceable trail artifact, not orphan cruft:

```json
{
  "created_at": "<ISO 8601 UTC timestamp>",
  "source_aar": "<path or identifier of the AAR>",
  "status": "pending-ingest",
  "goals": [
    {
      "title": "<goal line — goal-selection shape>",
      "details": "<elaboration summary + plan steps + success criteria + receipt path>",
      "priority": 10,
      "command": "",
      "completed": false
    }
  ],
  "escalated": []

From hummbl-io/agent-skills, Apache-2.0.

More from hummbl-io/agent-skills