Skip to content

Instantly share code, notes, and snippets.

@robertDouglass

robertDouglass/retrospective-investigate-canary-followups-1142-1141-01KS02TV.yaml

Last active May 19, 2026 14:13
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save robertDouglass/fc4d0511335f8e6150bcdccce2d43417 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save robertDouglass/fc4d0511335f8e6150bcdccce2d43417 to your computer and use it in GitHub Desktop.
Download ZIP
Spec Kitty retrospective.yaml — mission investigate-canary-followups-1142-1141-01KS02TV (#1160). [v2] All 5 actionable findings/proposals walked by HiC on 2026-05-19; 5 proposals state=accepted (1 existing + 4 promoted from not_helpful/gaps). Engineering trackers: #1161, #1162, #1163, #1164.
Raw
retrospective-investigate-canary-followups-1142-1141-01KS02TV.yaml
schema_version: '1'
mission:
mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
mid8: 01KS02TV
mission_slug: investigate-canary-followups-1142-1141-01KS02TV
mission_type: software-dev
mission_started_at: '2026-05-19T12:19:39+00:00'
mission_completed_at: '2026-05-19T13:52:21+00:00'
mode:
value: human_in_command
source_signal:
kind: environment
evidence: Operator (HiC) orchestrated the mission end-to-end via Claude Code. Runtime terminus retrospective
lifecycle was not opted in via SPEC_KITTY_RETROSPECTIVE or a charter `mode:` clause; this record was authored
post-hoc using the same RetrospectiveRecord schema and write_record writer the runtime would have used. HiC walked
all 5 actionable findings/proposals on 2026-05-19 and accepted each (3 with concurrent GitHub-issue tracking
handles).
status: completed
started_at: '2026-05-19T14:30:00+00:00'
completed_at: '2026-05-19T14:35:00+00:00'
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
helped:
- id: H-001
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:investigation:cheapest-first
note: 'Cheapest-first hypothesis ordering paid off in both investigations: #1142 H1 ruled out in ~5 min (clean canary venv
+ rc14) → H2 confirmed by static walk; #1141 H4 ruled out by inspecting one row in the captured failure → H3 ruled out
by code reading → narrowed to H1 sub-hypothesis 1 (silent fan-out failure). Saved hours of bisect time. Worth carrying
forward as the default investigation runbook shape.'
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: H-002
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:implementer:comment-draft-pause
note: Drafting the GitHub issue comment to research/comment-<n>.md first and pausing for HiC review before `gh issue
comment` (the post step) gave the operator a final shape-check at zero risk. The drafts both passed unchanged, but
the pause is cheap insurance against an irreversible GitHub-side mistake. Recommend codifying this as a mandatory
step for any WP whose owned_files include a `comment-*.md` artifact destined for `gh issue comment`.
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS02TWB6Y8VB5J9EGRMEABDX
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: H-003
target:
kind: doctrine_procedure
urn: urn:spec-kitty:procedure:mission-review:hard-gates
note: "The mission-review skill's hard-gate framework (contract / architectural / cross-repo E2E / issue-matrix) surfaced
two artifact gaps that no per-WP reviewer caught: issue-matrix.md was absent, and the missing evidence logs (after the
.gitignore trap) would have shipped invisibly. Gates 1+2 inheriting from origin/main on zero-diff missions is a useful
shortcut that saved ~10 min of CI time without sacrificing rigor."
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
not_helpful:
- id: N-001
target:
kind: glossary_term
urn: urn:spec-kitty:glossary:hypothesis-labels
note: spec.md abstracted the issue bodies' numbered hypotheses (`1.`, `2.`, ...) to H1/H2/H3/H4 labels for terminology
consistency. Every time the agent looked at the actual issue body it had to mentally re-map. The investigators
correctly threaded the mapping but the abstraction added no value; the issue body's numbering was already clear.
Recommend mission specs that mirror external issue numbering adopt the external numbering verbatim. HiC accepted as
synthesize_tactic on 2026-05-19.
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: N-002
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:tasks:owned-files-strict
note: "The WP template's strict owned_files enforcement was tripped by the FR-007 cross-namespace deliverable (this mission's
WPs needed to edit `kitty-specs/<parent-mission>/mission-exception.md` and that path was not in the declared owned_files).
Reviewer caught it as a polish-level note. The template should auto-detect FR-007-shape deliverables and extend owned_files
at /spec-kitty.tasks generation time. HiC accepted as synthesize_procedure + filed engineering tracker #1162 on 2026-05-19."
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
gaps:
- id: G-001
target:
kind: context_artifact
urn: urn:spec-kitty:artifact:gitignore-evidence-logs
note: 'Project-level `.gitignore *.log` silently excluded the three H1 evidence log files when WP01 ran `git add kitty-specs/.../research/`.
The implementer did not notice; HiC reviewer caught the gap and the fix-up landed as commit 9b47eb0fb via `git add -f`.
Filed as #1161 with two proposed remediation paths. Future investigation missions hit the same trap unless either .gitignore
whitelists `kitty-specs/**/research/*.log` or the WP-prompt template instructs implementers to use `git add -f` for evidence
logs. HiC accepted the synthesize_directive proposal on 2026-05-19.'
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: G-002
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:tasks:issue-matrix-scaffold
note: 'issue-matrix.md is a gate-required artifact (FR-037 of the mission-review skill) but /spec-kitty.tasks does not scaffold
it. WPs that declare GitHub-issue cross-references in tasks.md should trigger auto-scaffolding of issue-matrix.md with
one row per issue. The mission-review skill currently fails on missing matrix; the tasks pipeline should pre-empt that.
HiC accepted as synthesize_procedure + filed engineering tracker #1163 on 2026-05-19.'
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: G-003
target:
kind: doctrine_procedure
urn: urn:spec-kitty:procedure:retrospective:terminus-author
note: "The runtime terminus retrospective lifecycle is opt-in (SPEC_KITTY_RETROSPECTIVE env var / charter `mode:` clause).
Missions that have not opted in produce no retrospective.yaml at terminus — exactly what happened here. The mission-review
skill's retrospective-reminder section is currently the only escalation signal; there is no automatic enforcement. Either
make the terminus retrospective always-on, or surface 'retrospective missing' as a hard blocker in the post-merge mission
audit. HiC accepted the aggressive synthesize_directive (always-on) + filed engineering tracker #1164 on 2026-05-19."
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
proposals:
- id: 01KS09AX69Q7VTFXR0M5APNEG8
kind: synthesize_directive
payload:
kind: synthesize_directive
artifact_id: DIRECTIVE_evidence_logs_must_persist
body: "## DIRECTIVE_evidence_logs_must_persist\n\nInvestigation-mode missions whose WPs produce evidence logs under\n\
`kitty-specs/<mission>/research/*.log` MUST ensure those logs are\ncommitted to the mission's PR branch. The project-level
`.gitignore`\nrule `*.log` silently excludes them under default `git add` semantics.\n\nTwo acceptable remediation paths
(either satisfies the directive):\n\n1. **Whitelist** in the top-level `.gitignore`:\n\n ```\n !kitty-specs/**/research/*.log\n\
\ ```\n\n2. **Explicit `-f`** at commit time: the implementer must use\n `git add -f kitty-specs/<mission>/research/*.log`
and verify via\n `git status` that all expected log files appear in the index before\n commit.\n\nThe mission-review
post-merge audit MUST surface any evidence log that\nis referenced by a `research/comment-*.md`, `research/outcome-*.md`,
or\n`acceptance-matrix.json` but is absent from the merge commit. This rule\nexists to protect the NFR-003 reproducibility
contract: a reviewer\nfollowing the comment alone must be able to compare the cited log\noutput against the on-disk
artifact.\n\nReference cases:\n- spec-kitty PR #1160 (caught during mission-review, fixed in-PR)\n- Filed as spec-kitty#1161
(remediation tracking)\n"
body_hash: sha256:placeholder-recomputed-by-synthesize
scope:
actions:
- implement
- review
- mission-review
profiles:
- researcher-robbie
- implementer-ivan
- reviewer-renata
rationale: 'G-001 (the .gitignore evidence-log trap) is structural and will recur on every investigation mission unless
either the .gitignore is fixed or the implementer prompts are updated. A doctrine directive is the right artifact because
the rule applies across mission types and agent profiles. External tracker: spec-kitty#1161. HiC walked and accepted on
2026-05-19.'
state:
status: accepted
decided_at: '2026-05-19T15:30:00+00:00'
decided_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
apply_attempts: []
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
source_evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
approved_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
- id: 01KS09AX69Q7VTFXR0M5APNEG9
kind: synthesize_tactic
payload:
kind: synthesize_tactic
artifact_id: TACTIC_mirror_external_issue_numbering
body: "## TACTIC_mirror_external_issue_numbering\n\nWhen a mission spec references external trackers (GitHub issues, Linear\n\
tickets, etc.) that already carry their own labeling for sub-items\n(numbered hypotheses, lettered options, lettered
milestones, etc.),\nthe mission spec SHOULD adopt that labeling verbatim. Inventing\nparallel labels (e.g., abstracting
`1./2./3.` to `H1/H2/H3`) creates\na translation tax with no benefit and increases drift risk if the\nexternal tracker
is later edited.\n\nWhen the external numbering and the internal label both have a use\n(e.g., distinguishing hypotheses
across multiple missions whose\nexternal trackers all use `1./2./3.`), the spec MAY introduce a\nmission-local prefix
(e.g., `1142.1`, `1142.2`) that preserves the\nexternal numbering while disambiguating in cross-mission contexts.\n\
Pure relabeling (`1.` → `H1`) is the anti-pattern this tactic\naddresses.\n\nReference cases:\n- spec-kitty PR #1160
— spec.md abstracted #1141 and #1142 issue\n bodies' numbered hypotheses to H1/H2/H3/H4; investigators\n correctly
threaded the mapping but the abstraction added no\n value and required mental remapping at every reference.\n"
body_hash: sha256:placeholder-recomputed-by-synthesize
scope:
actions:
- specify
- plan
- tasks
profiles:
- researcher-robbie
- implementer-ivan
- architect-alphonso
- planner-priti
rationale: N-001 — when a mission references an external tracker that already carries its own labeling for sub-items,
inventing parallel labels (H1/H2/H3 for the issue body's 1./2./3.) creates a translation tax with no benefit. A
tactic (lighter than a directive) is the right artifact shape — this is guidance, not a hard rule, because
mission-local prefixes (e.g., 1142.1) are still permitted when they disambiguate cross-mission. HiC walked and
accepted on 2026-05-19.
state:
status: accepted
decided_at: '2026-05-19T15:30:00+00:00'
decided_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
apply_attempts: []
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
source_evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
approved_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
- id: 01KS09AX69Q7VTFXR0M5APNEGA
kind: synthesize_procedure
payload:
kind: synthesize_procedure
artifact_id: PROCEDURE_cross_namespace_owned_files_autodetect
body: "## PROCEDURE_cross_namespace_owned_files_autodetect\n\nAt `/spec-kitty.tasks` (or `finalize-tasks`) generation
time, when a\nWP's `requirement_refs` includes an FR whose spec.md text mandates an\nedit to a path outside the mission's
own directory, the generator\nMUST auto-extend the WP's `owned_files` list to include that target\npath.\n\n### Detection
heuristics\n\nFor each FR id in a WP's `requirement_refs`:\n\n1. Locate the FR's text in `spec.md`.\n2. Apply path-matching
heuristics:\n - Match `kitty-specs/<other-mission-slug>/...` paths where the slug\n differs from the current mission's
slug. The current mission's\n own paths are already covered by default ownership.\n - Match `architecture/.../...`
paths referenced as deliverable\n surfaces (look for verbs like \"update\", \"edit\", \"append to\").\n - Match
`docs/.../...` paths if the FR is documentation-shape.\n3. Append each matched path to the WP's `owned_files` list (deduped\n\
\ across the union of paths from all referenced FRs).\n\n### Validation\n\nAfter extending, run the existing `finalize-tasks
--validate-only`\nownership-overlap check against the extended lists. If two WPs would\nboth own the same cross-namespace
path, the validator surfaces it as\na normal ownership conflict — the auto-detection doesn't bypass\noverlap rules.\n\
\n### Reference cases\n\n- spec-kitty PR #1160 — WP01 and WP02 both had FR-007 deliverables\n targeting `kitty-specs/<parent-mission>/mission-exception.md`.\n\
\ Neither WP's owned_files listed that path. Reviewer caught it\n as polish-level; FR-007 was still delivered.\n-
Filed as spec-kitty#1162 (engineering implementation tracker).\n"
body_hash: sha256:placeholder-recomputed-by-synthesize
scope:
actions:
- tasks
profiles:
- implementer-ivan
- reviewer-renata
- architect-alphonso
rationale: "N-002 — strict owned_files enforcement tripped on this mission's FR-007 cross-namespace deliverables. The procedure
codifies auto-detection at /spec-kitty.tasks generation time. External tracker: spec-kitty#1162. HiC walked and accepted
on 2026-05-19."
state:
status: accepted
decided_at: '2026-05-19T15:30:00+00:00'
decided_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
apply_attempts: []
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
source_evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
approved_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
- id: 01KS09AX69Q7VTFXR0M5APNEGB
kind: synthesize_procedure
payload:
kind: synthesize_procedure
artifact_id: PROCEDURE_issue_matrix_autoscaffold
body: "## PROCEDURE_issue_matrix_autoscaffold\n\n`issue-matrix.md` is a gate-required mission artifact per FR-037 of\n\
the `spec-kitty-mission-review` skill (Gate 4). The post-merge\nmission-review audit FAILs the mission if the matrix
is missing, or\nif any row has an empty/`unknown` verdict, or if a\n`deferred-with-followup` row lacks a follow-up handle.\n\
\nAt `/spec-kitty.tasks` (or `finalize-tasks`) generation time:\n\n1. Scan `spec.md` and `tasks.md` for GitHub issue
references:\n - `#NNN` style links\n - Full `https://github.com/.../issues/NNN` URLs\n - `external_ref:` declarations
in WP frontmatter\n2. Deduplicate the issue set across all sources.\n3. If the set is non-empty, scaffold\n `kitty-specs/<slug>/issue-matrix.md`
with:\n - Header pointing at the canonical issue-matrix schema (inline\n the schema docs from the mission-review
skill).\n - One pre-populated row per referenced issue with columns:\n `issue` (linked), `repo`, `title` (fetched
via `gh issue view`\n if `gh` is authenticated, else blank), `verdict` (blank),\n `evidence_ref` (blank).\n\
\ - A note section explaining that operators fill in `verdict` and\n `evidence_ref` as the investigation completes.\n\
4. Commit the scaffold as part of the finalize-tasks commit.\n\n### Reference cases\n\n- spec-kitty PR #1160 — mission
referenced #1141 and #1142\n explicitly; matrix was authored during mission-review pass\n (commit f37053cb5) as a
fix-up rather than during planning.\n- Filed as spec-kitty#1163 (engineering implementation tracker).\n"
body_hash: sha256:placeholder-recomputed-by-synthesize
scope:
actions:
- tasks
profiles:
- implementer-ivan
- reviewer-renata
- planner-priti
rationale: "G-002 — issue-matrix.md is a gate-required artifact per the mission-review skill's FR-037 but /spec-kitty.tasks
does not scaffold it. The procedure adds the auto-scaffolding step. External tracker: spec-kitty#1163. HiC walked and
accepted on 2026-05-19."
state:
status: accepted
decided_at: '2026-05-19T15:30:00+00:00'
decided_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
apply_attempts: []
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
source_evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
approved_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
- id: 01KS09AX69Q7VTFXR0M5APNEGC
kind: synthesize_directive
payload:
kind: synthesize_directive
artifact_id: DIRECTIVE_terminus_retrospective_always_on
body: "## DIRECTIVE_terminus_retrospective_always_on\n\nThe runtime terminus retrospective lifecycle MUST be always-on
by\ndefault. Opt-out is permitted only via an explicit charter clause\n(e.g., `retrospective: disabled` or equivalent
doctrine-defined\nmarker), not via an environment variable or implicit project default.\n\n### Background\n\nThe current
default is opt-in via `SPEC_KITTY_ENABLE_SAAS_SYNC` env\nvar / charter `mode:` clause. Most missions therefore reach\n\
`mark-done` without authoring a `retrospective.yaml`; the\ncross-mission learning loop has no input on those missions;
and\n`spec-kitty retrospect summary` underreports.\n\n### Mitigations built into the directive\n\nTo soften the blast
radius of inverting the default:\n\n1. **Charter opt-out clause is well-documented**. The charter\n template scaffolded
by `spec-kitty charter init` ships the\n opt-out clause commented-out with explanation of when to use it.\n2. **Autonomous
mode produces minimal records**. When\n `mode: autonomous` is resolved (no HiC present), the runtime\n writes a
record with empty `helped/not_helpful/gaps` and\n `mode.source_signal.evidence = \"autonomous; no facilitator invoked\"\
`.\n This satisfies the always-on rule without forcing HiC-quality\n content.\n3. **`spec-kitty retrospect summary`
flags autonomous-empty\n records** as a separate category so the dashboard distinguishes\n \"no learning captured\"\
\ from \"learning captured but no findings\".\n4. **Migration deprecation flag**: a CLI flag\n `--allow-no-retrospective`
is available for the first N\n releases with a deprecation warning that points at the charter\n opt-out as the long-term
path.\n\n### Reference cases\n\n- spec-kitty PR #1160 — completed without an authored retrospective\n at terminus.
Retrospective was authored post-hoc via direct\n `RetrospectiveRecord` + `write_record` calls in a one-shot\n script,
then promoted to a public gist\n (https://gist.github.com/robertDouglass/fc4d0511335f8e6150bcdccce2d43417).\n- Filed
as spec-kitty#1164 (engineering implementation tracker).\n"
body_hash: sha256:placeholder-recomputed-by-synthesize
scope:
actions:
- next
- mission-review
profiles:
- orchestrator
- researcher-robbie
- implementer-ivan
- reviewer-renata
rationale: 'G-003 — opt-in default for terminus retrospective means most missions ship without a retrospective.yaml, and
the learning loop has no input. HiC explicitly chose the aggressive framing (directive, not tactic) on 2026-05-19, with
the four built-in mitigations (charter opt-out clause, autonomous-empty records, summary categorization, deprecation flag)
to manage the blast radius. External tracker: spec-kitty#1164.'
state:
status: accepted
decided_at: '2026-05-19T15:30:00+00:00'
decided_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
apply_attempts: []
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
source_evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
approved_by:
kind: human
id: robert@spec-kitty.ai
profile_id: human-in-charge
provenance:
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
runtime_version: 3.2.0rc14
written_at: '2026-05-19T15:30:00+00:00'
schema_version: '1'
skip_reason:
failure:
successor_mission_id:
Raw
retrospective.yaml
schema_version: '1'
mission:
mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
mid8: 01KS02TV
mission_slug: investigate-canary-followups-1142-1141-01KS02TV
mission_type: software-dev
mission_started_at: '2026-05-19T12:19:39+00:00'
mission_completed_at: '2026-05-19T13:52:21+00:00'
mode:
value: human_in_command
source_signal:
kind: environment
evidence: Operator (HiC) orchestrated the mission end-to-end via Claude Code. Runtime terminus retrospective
lifecycle was not opted in via SPEC_KITTY_RETROSPECTIVE or a charter `mode:` clause; this record was authored
post-hoc using the same RetrospectiveRecord schema and write_record writer the runtime would have used.
status: completed
started_at: '2026-05-19T14:30:00+00:00'
completed_at: '2026-05-19T14:35:00+00:00'
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
helped:
- id: H-001
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:investigation:cheapest-first
note: 'Cheapest-first hypothesis ordering paid off in both investigations: #1142 H1 ruled out in ~5 min (clean canary venv
+ rc14) → H2 confirmed by static walk; #1141 H4 ruled out by inspecting one row in the captured failure → H3 ruled out
by code reading → narrowed to H1 sub-hypothesis 1 (silent fan-out failure). Saved hours of bisect time. Worth carrying
forward as the default investigation runbook shape.'
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: H-002
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:implementer:comment-draft-pause
note: Drafting the GitHub issue comment to research/comment-<n>.md first and pausing for HiC review before `gh issue
comment` (the post step) gave the operator a final shape-check at zero risk. The drafts both passed unchanged, but
the pause is cheap insurance against an irreversible GitHub-side mistake. Recommend codifying this as a mandatory
step for any WP whose owned_files include a `comment-*.md` artifact destined for `gh issue comment`.
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS02TWB6Y8VB5J9EGRMEABDX
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: H-003
target:
kind: doctrine_procedure
urn: urn:spec-kitty:procedure:mission-review:hard-gates
note: "The mission-review skill's hard-gate framework (contract / architectural / cross-repo E2E / issue-matrix) surfaced
two artifact gaps that no per-WP reviewer caught: issue-matrix.md was absent, and the missing evidence logs (after the
.gitignore trap) would have shipped invisibly. Gates 1+2 inheriting from origin/main on zero-diff missions is a useful
shortcut that saved ~10 min of CI time without sacrificing rigor."
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
not_helpful:
- id: N-001
target:
kind: glossary_term
urn: urn:spec-kitty:glossary:hypothesis-labels
note: spec.md abstracted the issue bodies' numbered hypotheses (`1.`, `2.`, ...) to H1/H2/H3/H4 labels for terminology
consistency. Every time the agent looked at the actual issue body it had to mentally re-map. The investigators
correctly threaded the mapping but the abstraction added no value; the issue body's numbering was already clear.
Recommend mission specs that mirror external issue numbering adopt the external numbering verbatim.
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: N-002
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:tasks:owned-files-strict
note: The WP template's strict owned_files enforcement was tripped by the FR-007 cross-namespace deliverable (this
mission's WPs needed to edit `kitty-specs/<parent-mission>/mission-exception.md` and that path was not in the
declared owned_files). Reviewer caught it as a polish-level note. The template should auto-detect FR-007-shape
deliverables and extend owned_files at /spec-kitty.tasks generation time.
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
gaps:
- id: G-001
target:
kind: context_artifact
urn: urn:spec-kitty:artifact:gitignore-evidence-logs
note: 'Project-level `.gitignore *.log` silently excluded the three H1 evidence log files when WP01 ran `git add kitty-specs/.../research/`.
The implementer did not notice; HiC reviewer caught the gap and the fix-up landed as commit 9b47eb0fb via `git add -f`.
Filed as #1161 with two proposed remediation paths. Future investigation missions hit the same trap unless either .gitignore
whitelists `kitty-specs/**/research/*.log` or the WP-prompt template instructs implementers to use `git add -f` for evidence
logs.'
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: G-002
target:
kind: prompt_template
urn: urn:spec-kitty:prompt:tasks:issue-matrix-scaffold
note: issue-matrix.md is a gate-required artifact (FR-037 of the mission-review skill) but /spec-kitty.tasks does not
scaffold it. WPs that declare GitHub-issue cross-references in tasks.md should trigger auto-scaffolding of
issue-matrix.md with one row per issue. The mission-review skill currently fails on missing matrix; the tasks
pipeline should pre-empt that.
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
- id: G-003
target:
kind: doctrine_procedure
urn: urn:spec-kitty:procedure:retrospective:terminus-author
note: The runtime terminus retrospective lifecycle is opt-in (SPEC_KITTY_RETROSPECTIVE env var / charter `mode:`
clause). Missions that have not opted in produce no retrospective.yaml at terminus — exactly what happened here. The
mission-review skill's retrospective-reminder section is currently the only escalation signal; there is no automatic
enforcement. Either make the terminus retrospective always-on, or surface 'retrospective missing' as a hard blocker
in the post-merge mission audit.
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
evidence_event_ids:
- 01KS088208QV3BAP4G3ZJB42AN
actor:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
captured_at: '2026-05-19T14:30:00+00:00'
proposals:
- id: 01KS08F9E3SN3G2RDRPY2HZWN5
kind: synthesize_directive
payload:
kind: synthesize_directive
artifact_id: DIRECTIVE_evidence_logs_must_persist
body: "## DIRECTIVE_evidence_logs_must_persist\n\nInvestigation-mode missions whose WPs produce evidence logs under\n\
`kitty-specs/<mission>/research/*.log` MUST ensure those logs are\ncommitted to the mission's PR branch. The project-level
`.gitignore`\nrule `*.log` silently excludes them under default `git add` semantics.\n\nTwo acceptable remediation paths
(either satisfies the directive):\n\n1. **Whitelist** in the top-level `.gitignore`:\n\n ```\n !kitty-specs/**/research/*.log\n\
\ ```\n\n2. **Explicit `-f`** at commit time: the implementer must use\n `git add -f kitty-specs/<mission>/research/*.log`
and verify via\n `git status` that all expected log files appear in the index before\n commit.\n\nThe mission-review
post-merge audit MUST surface any evidence log that\nis referenced by a `research/comment-*.md`, `research/outcome-*.md`,
or\n`acceptance-matrix.json` but is absent from the merge commit. This rule\nexists to protect the NFR-003 reproducibility
contract: a reviewer\nfollowing the comment alone must be able to compare the cited log\noutput against the on-disk
artifact.\n\nReference cases:\n- spec-kitty PR #1160 (caught during mission-review, fixed in-PR)\n- Filed as spec-kitty#1161
(remediation tracking)\n"
body_hash: sha256:placeholder-recomputed-by-synthesize
scope:
actions:
- implement
- review
- mission-review
profiles:
- researcher-robbie
- implementer-ivan
- reviewer-renata
rationale: G-001 (the .gitignore evidence-log trap) is structural and will recur on every investigation mission unless
either the .gitignore is fixed or the implementer prompts are updated. A doctrine directive is the right artifact
because the rule applies across mission types and agent profiles. Already tracked externally as spec-kitty#1161.
Marking pending until HiC reviews the body.
state:
status: pending
decided_at:
decided_by:
apply_attempts: []
provenance:
source_mission_id: 01KS02TVCYPQXQ9DX1Z39SXZ6K
source_evidence_event_ids:
- 01KS04PS2PP7JH4N5D8W72V138
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
approved_by:
provenance:
authored_by:
kind: agent
id: claude:opus-4-7
profile_id: orchestrator
runtime_version: 3.2.0rc14
written_at: '2026-05-19T14:35:00+00:00'
schema_version: '1'
skip_reason:
failure:
successor_mission_id:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment