mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
docs(neckbeard): add skip-transparent lesson capture to phase 9 closeout
Implements issue #377 (journey dossier F2, ADAPT verdict): phase 9 closeout now records lesson capture per stages.md Stage 6 "Deliver and learn" — either the reusable lesson(s) and their durable destination (skill, memory, or project docs), or an explicit "no reusable lesson identified" determination. Mirrors skip transparency: silent omission is prohibited. Terminal-state semantics stay intact — lessons are recorded IN the terminal record; a fired trigger or follow-up starts a new change request via phase 1 intake. - references/journey.md: phase 9 Output row gains the lesson-capture field; phase-continuity row updated ("terminal; triggers and lessons recorded in the terminal record"). - references/delivery-packet.md: group (i) row gains lesson capture; terminal semantics cover lessons alongside triggers; skip-transparency doctrine cross-referenced for closeout lessons. - templates/delivery-packet.md: section (i) fillable "Lessons captured" field with durable-destination note + example line. - references/lifecycle.md: intro, terminal-states closeout note, and closeout row aligned with the extended group-(i) field set. - evals/evals.json: expected_output + assertions extended in bug-fix- reproduction-regression and refactor-characterization-architecture-review (13 IDs stable). stages.md untouched: Stage 6 already mandates lesson capture; journey/packet now consume it. README table unchanged (still accurate). Closes #377 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
co-authored by
factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
parent
11a5be93ef
commit
7c0de4cb76
File diff suppressed because one or more lines are too long
@@ -37,7 +37,7 @@ into another or left to implication.
|
||||
| **(f)** | **Design: architecture delta / decisions / risks / compatibility / migration / rollback** | Architecture delta (or a documented "no delta" determination); decisions and rejected alternatives; risks; compatibility analysis; migration strategy; rollback plan. |
|
||||
| **(g)** | **Plan: spec / acceptance criteria / test strategy / task plan / verification report paths** | Path to `SPEC.md`; acceptance criteria mapping; test strategy; path to `TASK-PLAN.md`; path to the QA verification plan; verification report paths. |
|
||||
| **(h)** | **Gates: verdicts / assumptions / rejected alternatives / unresolved boundaries / evidence pointers** | A verdict per gate (identifier, pass/conditional/blocked, evidence, head SHA); assumptions; rejected alternatives; unresolved boundaries; pointers to evidence artifacts. |
|
||||
| **(i)** | **Lifecycle: PR number / CI status / review status / final verified head SHA / release status** | PR (or review-submission) number; CI status; review status; the **final verified head SHA**; release status; terminal lifecycle state and its evidence; **rollback/follow-up triggers** recorded at closeout (what would cause re-entry). |
|
||||
| **(i)** | **Lifecycle: PR number / CI status / review status / final verified head SHA / release status** | PR (or review-submission) number; CI status; review status; the **final verified head SHA**; release status; terminal lifecycle state and its evidence; **rollback/follow-up triggers** recorded at closeout (what would cause re-entry); **lesson capture** recorded at closeout per Stage 6 ([stages.md](stages.md)) — the reusable lesson(s) with their durable destination, or an explicit "no reusable lesson identified" determination. |
|
||||
|
||||
Group (e) and group (h) carry the fields that make skip transparency and gate
|
||||
discipline auditable; see their rules below.
|
||||
@@ -129,11 +129,14 @@ terminal state is **not re-opened by a later phase**. New work starts a new pack
|
||||
**ready** packet that fails a gate or CI returns to **in-review** (not terminal);
|
||||
only a blocked verdict makes it **blocked**.
|
||||
|
||||
Rollback/follow-up triggers are recorded **in** the terminal record at closeout
|
||||
(see group (i)); they document what would cause re-entry but do not re-open the
|
||||
Rollback/follow-up triggers and closeout lesson capture (per Stage 6,
|
||||
[stages.md](stages.md)) are recorded **in** the terminal record at closeout
|
||||
(see group (i)); they document what would cause re-entry — and what was
|
||||
learned, or that no reusable lesson was identified — but do not re-open the
|
||||
packet. When a recorded trigger fires, the follow-up work starts as a new change
|
||||
request through phase 1 intake, carrying the trigger reference from the closed
|
||||
packet's record.
|
||||
packet's record. A captured lesson lands in its durable destination (skill,
|
||||
memory, or project docs) directly; it is not consumed by re-opening this packet.
|
||||
|
||||
## Blocked-state semantics
|
||||
|
||||
@@ -264,6 +267,9 @@ packet records "no specialist selected — no applicability signal triggered," a
|
||||
work proceeds on the neckbeard spine; this is neither a silent omission nor a
|
||||
fabricated reason. The stages reference (`references/stages.md`) and routing table
|
||||
(`references/routing-table.md`) define the signals and skip rules cited here.
|
||||
The same doctrine governs closeout lesson capture: recording an explicit
|
||||
"no reusable lesson identified" determination in group (i) is a recorded skip,
|
||||
not an omission; leaving the field blank is prohibited.
|
||||
|
||||
## Portability
|
||||
|
||||
|
||||
@@ -131,7 +131,7 @@ assessed position under this journey's rules.
|
||||
|---|---|
|
||||
| **Owner** | Release authority holder (explicit authorization required beyond merge authority; see [risk-authority-gates.md](risk-authority-gates.md) and [lifecycle.md](lifecycle.md)) |
|
||||
| **Input** | Phase 8 output: readiness confirmed at the exact final head SHA; change merged (or equivalent accepted) into the protected target. Packet group (i) shows merge evidence. |
|
||||
| **Output** | Packet group (i) completed: **terminal lifecycle state** (`merged`, `closed`, `blocked`, or `released`) recorded with evidence — merge commit SHA, release evidence (tag, artifact, deploy confirmation, post-release smoke check), or close reason — plus **rollback/follow-up triggers**: the conditions that would cause re-entry after closeout (e.g., a post-release regression requiring rollback, or an operational discovery). The packet transitions to a terminal state and is not re-opened; operational or post-release discoveries route to a **new** change request via phase 1 intake, never to the terminal packet. |
|
||||
| **Output** | Packet group (i) completed: **terminal lifecycle state** (`merged`, `closed`, `blocked`, or `released`) recorded with evidence — merge commit SHA, release evidence (tag, artifact, deploy confirmation, post-release smoke check), or close reason — plus **rollback/follow-up triggers**: the conditions that would cause re-entry after closeout (e.g., a post-release regression requiring rollback, or an operational discovery); plus **lesson capture** per Stage 6 "Deliver and learn" ([stages.md](stages.md)): either the reusable lesson(s) and their durable destination (skill, memory, or project docs), or an explicit "no reusable lesson identified" determination — silent omission is prohibited. The packet transitions to a terminal state and is not re-opened; operational or post-release discoveries route to a **new** change request via phase 1 intake, never to the terminal packet. |
|
||||
| **Gate** | **Release gate:** release activity (tagging, publishing, deploying) requires **explicit authorization distinct from merge authority**. Merge alone does not imply release authorization. Post-release verification evidence (smoke check, deploy confirmation) is recorded before the `released` terminal state is declared. |
|
||||
| **Escalation** | Release authority is not granted; or post-release verification reveals a regression requiring rollback; or a change-freeze window blocks deployment (enterprise mode). |
|
||||
| **Platform mapping** | **GitHub mode:** release via tag/publish per repository conventions; release authority is a separate grant from merge authority. **Enterprise mode:** release via enterprise pipeline (CAB approval, change-manager sign-off, change-freeze compliance); deploy confirmation recorded. |
|
||||
@@ -305,7 +305,7 @@ named delivery-packet field groups:
|
||||
| 6 — Implementation | Commits, (c) head SHA updated | Phase 7 (input: complete implementation) |
|
||||
| 7 — Review + verification | (h) gate 4 + gate 5 verdicts, `VERIFICATION.md` | Phase 8 (input: verdicts at known SHA) |
|
||||
| 8 — Readiness | (i) PR/CI/review/final verified head SHA | Phase 9 (input: merged change, readiness evidence) |
|
||||
| 9 — Release + closeout | (i) terminal state + evidence + rollback/follow-up triggers | Record complete (terminal; triggers are recorded in the terminal record, not consumed — re-entry starts a new packet via phase 1 intake) |
|
||||
| 9 — Release + closeout | (i) terminal state + evidence + rollback/follow-up triggers + lesson capture (or "no reusable lesson identified") | Record complete (terminal; triggers and lessons are recorded in the terminal record, not consumed — re-entry starts a new packet via phase 1 intake, carrying the lesson reference) |
|
||||
|
||||
Every field group written by a phase is consumed by a named later phase or
|
||||
recorded as terminal evidence. No output is orphaned.
|
||||
|
||||
@@ -13,7 +13,8 @@ change-request journey ([journey.md](journey.md)) and the five gates
|
||||
([stages.md](stages.md)). It records its outcomes in the delivery packet
|
||||
([delivery-packet.md](delivery-packet.md)), field group (i) — PR/review-submission
|
||||
number, CI status, review status, **final verified head SHA**, release status,
|
||||
and terminal-state evidence plus rollback/follow-up triggers. Stop and escalation
|
||||
and terminal-state evidence plus rollback/follow-up triggers and closeout lesson
|
||||
capture. Stop and escalation
|
||||
rules live in [risk-authority-gates.md](risk-authority-gates.md).
|
||||
|
||||
## Two modes, one structure
|
||||
@@ -331,9 +332,11 @@ These are the same terminal states defined by the packet
|
||||
([delivery-packet.md](delivery-packet.md), lifecycle states) and by journey
|
||||
phase 9 closeout ([journey.md](journey.md)). A terminal packet is never
|
||||
re-opened; new work starts a new packet. Closeout also records
|
||||
**rollback/follow-up triggers** — what would cause re-entry — in group (i);
|
||||
a fired trigger starts a new change request via phase 1 intake, it does not
|
||||
resurrect the terminal packet.
|
||||
**rollback/follow-up triggers** — what would cause re-entry — and **lesson
|
||||
capture** per Stage 6 "Deliver and learn" ([stages.md](stages.md)): the reusable
|
||||
lesson(s) with their durable destination, or an explicit "no reusable lesson
|
||||
identified" determination — in group (i); a fired trigger starts a new change
|
||||
request via phase 1 intake, it does not resurrect the terminal packet.
|
||||
|
||||
### Reduced paths still terminate with evidence
|
||||
|
||||
@@ -375,10 +378,11 @@ exists in [delivery-packet.md](delivery-packet.md).
|
||||
| Monitor review | Review status | (i) |
|
||||
| Bind verdicts per review round | **Final verified head SHA** | (i) |
|
||||
| Assess release readiness and execute release | Release status (with post-release verification evidence) | (i) |
|
||||
| Close out | Terminal lifecycle state + terminal-state evidence (merge SHA / close reason / blocker evidence / release evidence) + rollback/follow-up triggers | (i) |
|
||||
| Close out | Terminal lifecycle state + terminal-state evidence (merge SHA / close reason / blocker evidence / release evidence) + rollback/follow-up triggers + lesson capture (or "no reusable lesson identified") | (i) |
|
||||
|
||||
Field group (i) — PR number, CI status, review status, final verified head SHA,
|
||||
release status, terminal-state evidence, and rollback/follow-up triggers — is
|
||||
release status, terminal-state evidence, rollback/follow-up triggers, and
|
||||
lesson capture — is
|
||||
the exact set this reference populates; the match is bidirectional (no field
|
||||
here that the packet lacks, and no group-(i) field the lifecycle never writes).
|
||||
|
||||
|
||||
@@ -151,6 +151,7 @@ gate-1 (architecture/design delta) | pass | a1b2c3d | ARCHITECTURE-DELTA.md | no
|
||||
- **Terminal lifecycle state:** _[fill: merged / closed / blocked / released]_
|
||||
- **Terminal state evidence:** _[fill: merge commit SHA, closure reason, or blocker reference]_
|
||||
- **Rollback/follow-up triggers:** _[fill: conditions that would cause re-entry after closeout — e.g., a post-release regression requiring rollback or an operational discovery; write "none identified" if there are none. Recorded in the terminal record; any follow-up starts a new change request via phase 1 intake, never by re-opening this packet.]_
|
||||
- **Lessons captured:** _[fill: reusable lesson(s) captured per Stage 6 "Deliver and learn" with their durable destination — skill, memory, or project docs — e.g., "multi-byte input handling lesson → project docs runbook"; or write "no reusable lesson identified". Recorded in the terminal record; silent omission is prohibited.]_
|
||||
|
||||
**Example (populated lifecycle):**
|
||||
|
||||
@@ -165,6 +166,8 @@ Terminal state evidence: merge commit 8c31ef4
|
||||
Rollback/follow-up triggers: post-release smoke check failure in the
|
||||
export path; operational discovery of
|
||||
multi-byte handling in adjacent endpoints
|
||||
Lessons captured: multi-byte input boundary lesson →
|
||||
project docs runbook (export section)
|
||||
```
|
||||
|
||||
### Blocked-state record
|
||||
|
||||
Reference in New Issue
Block a user