| name | engagement-record-emission |
| description | Marker contract for Segment-A maintainer-evidence and cross-session engagement-state preservation. Use when an agent exits its phase. DO NOT USE FOR: runtime code execution, test writing, or PR creation. |
Engagement Record Emission
This skill defines the SMC-20 engagement-record marker contract and schema used to preserve agentic engagement state across sessions.
When to Use
Use this skill when an upstream agent (Experience-Owner, Solution-Designer, or Issue-Planner) exits its respective phase. It provides a structured, durable way to record the decisions, classifications, and engineer choices made during the phase, allowing subsequent sessions or downstream agents to skip repetitive questioning on settled decisions.
Also a writer (#974): the open-for-work conversation. skills/open-for-work/SKILL.md records its checkpoint decisions — the worth-it doors, the affirmation gate, and brief approval on the routine arm — into <!-- engagement-record-experience-{ID} --> at schema_version: 2, because that conversation is the experience-replacement for standalone work (#957 D5). It is not an upstream agent, so it is named here explicitly rather than inferred, on the same footing as the orchestration-phase carve-out below. Cumulative-write obligation: that conversation reaches three checkpoints at different moments, and this family is post-new with latest-createdAt-wins on read — so a later marker carrying only the later decision orphans the earlier one. Write one marker at conversation exit carrying every decision, or make each later write carry the full accumulated set.
When Not to Use
Do not use this skill for runtime code execution, test writing, or PR creation. It is strictly a cognitive-evidence and state-preservation contract. Do not emit these markers in downstream phases. Exception (v2 carve-out, #655 S3): the review phase is explicitly permitted to emit <!-- engagement-record-review-{PR} --> as a PR comment after the review judge verdict; this marker is PR-keyed (not issue-keyed) and governed by SMC-23.
Marker Shape
Engagement records are emitted as GitHub issue comments containing a YAML code block wrapped inside a unique HTML comment marker representing the phase:
<!-- engagement-record-{phase}-{ISSUE_ID_OR_PR} -->
Where {phase} is one of experience, design, plan (at schema_version: 2), orchestration (at schema_version: 3, introduced in v1.3 / #577), or review (at schema_version: 4, introduced in #655 S3, PR-keyed); and {ISSUE_ID_OR_PR} is the GitHub issue ID (for experience/design/plan/orchestration phases) or PR number (for the review phase).
For example:
<!-- engagement-record-design-575 -->
<!-- engagement-record-orchestration-577 -->
<!-- engagement-record-review-42 --> (PR #42)
Canonical Schema
The canonical YAML schema for the engagement-record payload is structured as follows:
schema_version: 3
phase: orchestration
capture_session: "normal-orchestration-v3"
load_bearing_decisions:
- decision_id: conductor-scope-classification
classification: load-bearing
audit_rationale: "Rationale..."
engineer_choice: "Choice..."
teaching_paragraph_excerpt: "..."
articulation_text: "..."
articulation_status: pending
recommendation_shift_trigger: engineer-pushback
Persistence Rule
Multiple engagement-record markers may be written to the same issue for a given (phase, issue). The latest-timestamp marker comment (based on GitHub comment createdAt field) wins on resume-read. This inherits the standard SMC-08 / SMC-17 latest-comment-wins convention.
Write path (issue #893): skills/session-memory-contract/scripts/persist-marker.ps1 (family engagement-record, post-new, with a payload-only validator adapter that parses the candidate via Read-EngagementRecords -InMemoryMarkers before any network write) is the ONLY documented write path for the experience, design, plan, and orchestration phases — never a hand-composed gh issue comment call. What that rule buys is a single audited writer — not protection from updated_at advancement. This family is post-new, so the write POSTs a fresh comment and advances nothing; the hazard arrives when a write replaces a whole body already carrying someone else's marker. See skills/session-memory-contract/references/handoff-markers.md § What the write-path rule buys for the write-shape split. review-phase markers (engagement-record-review-{PR}) are a known v1 registry gap and stay hand-authored: the family registry declares TargetSurface: issue uniformly, but the review phase is PR-keyed, so a review-phase write through the script is refused by the surface preflight until that gap is closed.
Schema Versioning Policy
Tooling that reads engagement records MUST throw an error on encountering an unknown schema_version value.
- Additive-field policy: Within a schema version, new optional fields may be added by writers. Readers MUST ignore unknown optional fields without throwing errors.
- Breaking changes: Any renamed fields, changed enum sets, or new required fields require incrementing the schema version. Readers built against v1.1 throw on v2 markers, and readers built against v1.2 throw on v3 markers — this is intentional; per #576 D4 and #577 D4 the helper is updated in lockstep and
.claude-plugin/plugin.json is bumped to invalidate cached older readers. A backward-compatibility guard ensures that phase: orchestration requires schema_version >= 3 to prevent reading orchestration markers with older schemas. A parallel guard requires phase: review to have schema_version >= 4: frame-engagement-record-core.ps1 throws if a review-phase marker carries schema_version < 4.
Resume-Read Protocol
Downstream/upstream agents load engagement records at phase startup by calling the helper:
Read-EngagementRecords -IssueNumber {ID} [-Phase experience|design|plan|orchestration|review] [-PullRequestNumber {PR}] [-InMemoryMarkers <string[]>] [-AcceptLegacy]
If a record is returned for a given decision_id, the agent activates the same-decision-resume skip rule in skills/solution-authoring/SKILL.md to reuse the captured decision and suppress re-firing the question. For review-phase records, pass -PullRequestNumber {PR} instead of (or alongside) -IssueNumber. See SMC-23.
articulation_status Transitions
pending: Written by the authoring agent at phase exit.complete / incomplete: Written by the CE Gate evaluator after assessing the evidence.
Initial state: writers SHOULD emit articulation_text: "" (empty string) paired with articulation_status: pending at phase exit. This is the documented initial state, not an error. The CE Gate (#578) closes the loop by evaluating and transitioning to complete or incomplete.
Markdown Bullet ↔ YAML Key Map
Writers and validation tooling MUST enforce the following mapping when translating between the Markdown mirror's bullet fields and the YAML engagement-record's keys:
| Markdown Bullet Field | YAML Payload Key |
|---|
**Classification** | classification |
**Engineer choice** | engineer_choice |
**Audit rationale** | audit_rationale |
**Decision brief excerpt** | teaching_paragraph_excerpt |
**Articulation text** | articulation_text |
**Articulation status** | articulation_status |
**Recommendation shift trigger** | recommendation_shift_trigger |
Injection Policy
To prevent Markdown escaping and parsing errors on user-typed fields, writers MUST adhere to the following injection policy:
- Writers MUST use YAML block-scalar
|- for all multi-line user-typed fields (audit_rationale, articulation_text, engineer_choice).
- Literal triple-backtick fence lines within those fields are strictly rejected at write time.
capture_session Policy
The capture_session is a free-form string field that tracks the execution context. The recommended convention is:
{trigger}-{phase}-v{major}[.{minor}]
Where:
{trigger} ∈ normal | manual | replay{phase} ∈ experience | design | plan | orchestration | review
Readers MUST NOT reject malformed values, but validation tooling may emit warnings on non-conforming strings.
Related
- session-memory-contract (
SMC-20)
- solution-authoring (
same-decision-resume skip rule)
- frame-engagement-record-core (
Read-EngagementRecords helper)
- Note on Slug Disambiguation: The customer-experience skill's prose use of "named decisions" refers to the same concept; engagement-record emission persists load-bearing classifications under the same unique slug namespace.
Gotchas
| Trigger | Gotcha | Fix |
|---|
| Mismatched schema version | An older reader reads a v2 marker and crashes or drops decisions. | Enforce throwing on unknown schema_version and coordinate version bumps across all tools. |
-AcceptLegacy cross-issue contamination | Before the MF2 fix, -AcceptLegacy bypassed the issue-number check, allowing markers from foreign issues to appear in results. | Never pass foreign-issue markers alongside -AcceptLegacy; the issue-number check is now always enforced. |
| Mixed-state issues | Issues that completed earlier phases pre-#576 and later phases post-#576 carry asymmetric resume coverage. | schema_version: 1 markers (from #575) ARE read by the helper — Read-EngagementRecords accepts both v1 and v2 markers at parse time, so mixed-state issues with v1 design-phase markers and v2 plan-phase markers resume correctly across both phases. Only purely-pre-#571 markers (lacking schema_version entirely) require -AcceptLegacy to read; without that switch, they ARE opaque. |
| Comment-burst halt-on-failure | If engagement-record emission fails after the completion marker is posted, credit-input would still be posted. | Script-enforced (issue #893): the phase-exit burst is one persist-marker.ps1 -BurstManifest invocation whose halt-on-first-failure execution stops before credit-input when engagement-record write fails — the completion marker (already landed) stands, the phase is still marked complete, and the script's ⚠️ warning line must be relayed to the terminal. |
| Markdown summary policy | Markdown bullet lists are human-readable mirrors of the YAML marker payload. | Automation tools must read only the YAML block; the Markdown bullets are for human review/audits only. |
| Articulation_text empty-window UX | articulation_text: "" renders as a blank bullet block in the human-readable Markdown section, which looks like an authoring error. | The Markdown mirror H3 sub-section in agent bodies appends the comment <!-- CE Gate articulation pending per #578 --> to clarify that evaluation has not yet occurred. |
Frame Ports Filled By This Skill
None. This skill provides supporting methodology and specifications rather than a direct frame port.
