Skip to content

Retrospective Schema and Events Reference

This reference documents the retrospective.yaml schema, proposal types, retrospective status events, and synthesizer exit codes. For how to use the retrospective loop, see How to Use the Retrospective Learning Loop.


retrospective.yaml schema

Retrospective records are stored at:

.kittify/missions/<mission_id>/retrospective.yaml

The file is keyed by canonical mission ULID, not display number. The schema is implemented by specify_cli.retrospective.schema.RetrospectiveRecord.

FieldTypeRequiredDescription
schema_versionstringYesLiteral "1"
missionobjectYesMission identity: mission_id, mid8, mission_slug, mission_type, timestamps
modeobjectYesRetrospective mode: autonomous or human_in_command, plus source signal
statusstringYesPersisted values: completed, skipped, or failed. pending exists in the model but the writer refuses to persist it.
started_atISO 8601 timestampYesWhen retrospective handling started
completed_atISO 8601 timestampConditionalRequired when status: completed
actorobjectYesActor that authored the record
helpedlist[Finding]NoArtifacts, directives, tactics, tests, or context that helped
not_helpfullist[Finding]NoTargets flagged as not helpful during the mission
gapslist[Finding]NoGovernance or context gaps identified during the mission
proposalslist[Proposal]NoStructured change proposals (see Proposal kinds below)
provenanceobjectYesRecord author, runtime version, write timestamp, schema version
skip_reasonstringConditionalRequired when status: skipped
failureobjectConditionalRequired when status: failed
successor_mission_idULID stringNoFollow-up mission identity when one is created

Finding shape

helped, not_helpful, and gaps entries share the same shape:

FieldTypeDescription
idstringFinding identifier unique within the record
target.kindstringOne of doctrine_directive, doctrine_tactic, doctrine_procedure, drg_edge, drg_node, glossary_term, prompt_template, test, context_artifact
target.urnstringTarget URN
notestringHuman-readable note, max 2000 characters
provenance.source_mission_idULID stringMission that produced the evidence
provenance.evidence_event_idslist[ULID]Event IDs that support the finding
provenance.actorobjectActor that captured the finding
provenance.captured_attimestampCapture timestamp

Generator-shape records (retrospect create)

spec-kitty retrospect create (and backfill) write the generator record shape read by specify_cli.retrospective.reader.read_gen_record; its original contract is the archived kitty-specs/retrospective-default-policy-01KS049J/contracts/retrospective-record.schema.json, which is a frozen historical record and is not edited (the kitty-specs/ archive root is byte-preserved). The live machine authority for the optional payload added in this release is the discriminated ProposalPayload union in src/specify_cli/retrospective/schema.py. The shape differs from the nested schema above in two ways that matter to synthesize:

Nested recordGenerator record
proposals[].idULIDp-001, p-002, …
proposals[].actionkind + discriminated payloadfree-text suggested_action (+ optional payload)

A generator-shape proposal may therefore carry an optional payload block, validated against the same ProposalPayload union synthesize applies — there is no second payload schema. When it does, synthesize translates the proposal into a nested proposal (a derived ULID id, always pending: auto_applicable is a hand-editable flag, not an accept decision). Select it with --proposal-id; it is never part of the default batch. A proposal without a payload is not plannable; retrospect create writes none of its own, and grading findings into payloads is tracked in #3947.

Every synthesize run on a generator-shape record adds a top-level diagnostics object to the JSON envelope (and a matching warning on the Rich surface):

"diagnostics": {
"record_schema": "generator",
"findings": {"helped": 0, "not_helpful": 19, "gaps": 2, "proposals": 0},
"proposals_translated": 0,
"proposals_planned": 0,
"untranslatable": [],
"next_action": "This retrospective uses the generator record schema and carries no proposals, …"
}

untranslatable names every proposal that could not be translated, with the reason. Nested-schema records never carry the block, so their envelopes are unchanged.


Proposal kinds

Each proposal in the proposals list has id, kind, payload, rationale, state, and provenance. Proposal IDs and evidence event IDs are ULIDs. state.status is one of pending, accepted, rejected, applied, or superseded.

The synthesizer applies the effective batch: accepted proposal IDs plus every flag_not_helpful proposal. flag_not_helpful is auto-included in that batch, but no proposal mutates project state unless the operator passes --apply.

add_glossary_term

Add a new term to the project glossary.

FieldRequiredDescription
payload.kindYesadd_glossary_term
payload.term_keyYesSafe term key, e.g. lifecycle-terminus
payload.definitionYesHuman-readable definition
payload.definition_hashYesHash of the proposed definition
payload.related_termsNoRelated term keys

update_glossary_term

Update an existing glossary term’s definition or scope.

FieldRequiredDescription
payload.kindYesupdate_glossary_term
payload.term_keyYesExisting term key to update
payload.definitionYesNew definition
payload.definition_hashYesHash of the proposed definition
payload.related_termsNoRelated term keys

flag_not_helpful

Flag a DRG or doctrine artifact as not helpful. This proposal kind is auto-included in the effective apply batch, but it still writes only when --apply is used.

FieldRequiredDescription
payload.kindYesflag_not_helpful
payload.target.kindYesTarget kind
payload.target.urnYesTarget URN

add_edge

Add a relationship in the project-local DRG overlay.

FieldRequiredDescription
payload.kindYesadd_edge
payload.edge.from_nodeYesSource node URN
payload.edge.to_nodeYesTarget node URN
payload.edge.kindYesEdge kind

The schema also defines remove_edge for compatibility, but the current apply path does not provide an operator-facing apply handler for it.

rewire_edge

Replace one edge with another.

FieldRequiredDescription
payload.kindYesrewire_edge
payload.edge_oldYesExisting edge object
payload.edge_newYesReplacement edge object

synthesize_directive / synthesize_tactic / synthesize_procedure

Create or update project-local doctrine artifacts.

FieldRequiredDescription
payload.kindYesOne of the three synthesize_* kinds
payload.artifact_idYesSafe artifact identifier
payload.bodyYesArtifact body
payload.body_hashYesHash of the body
payload.scope.actionsNoAction scope list
payload.scope.profilesNoProfile scope list

Synthesizer acceptance criteria

The synthesizer accepts a proposal when:

  • All required fields are present and valid
  • No conflicting proposal exists in the same batch (same target with different values)
  • The referenced artifacts (evidence event IDs) still resolve in the event log

The synthesizer rejects a proposal when:

  • Required fields are missing
  • Referenced evidence event IDs no longer resolve in the source mission event log
  • The term key or artifact ID is malformed
  • A conflicting proposal exists (fail-closed: the entire conflicting set is rejected)

Retrospective status events

Retrospective lifecycle events are written to kitty-specs/<slug>/status.events.jsonl alongside other mission lifecycle events. Filter by event name prefix retrospective. to isolate them.

Event nameWhen emittedDescription
retrospective.requestedAt mission terminusThe runtime requested a retrospective
retrospective.startedFacilitator dispatchedThe retrospective facilitator began execution
retrospective.proposal.generatedPer proposalOne event per generated proposal (×N)
retrospective.completedFacilitator finishedThe retrospective completed successfully
retrospective.skippedOperator skippedThe operator explicitly skipped (HiC mode only)
retrospective.failedFacilitator failedThe facilitator encountered an error
retrospective.proposal.appliedPer applied proposalOne event per applied proposal (×N)
retrospective.proposal.rejectedPer rejected proposalOne event per proposal rejected during apply

The retrospective.skipped event and the corresponding status: skipped in the YAML record are both required. Neither alone is sufficient to record a valid skip.


Synthesizer exit codes

spec-kitty agent retrospect synthesize uses the following exit codes:

Exit codeMeaningAction required
0Success — dry-run complete (no changes, including an empty generator-shape batch, which is reported through diagnostics) or proposals applied successfullyNone
1Invalid project root, unresolvable mission handle, or other command errorFix invocation/project state
2I/O error reading retrospective dataInspect filesystem permissions and paths
3Retrospective record missing or malformedCreate or repair .kittify/missions/<mission_id>/retrospective.yaml
4Conflicts present during --applyResolve conflicts before applying
5Stale evidence or invalid payload rejection during --applyRefresh evidence or fix proposal payloads

The --apply flag is required for any mutations. Omitting --apply always exits 0 on a valid dry-run regardless of proposal count or detected conflicts.

For the current exit code list, run:

Terminal window
uv run spec-kitty agent retrospect synthesize --help

See Also