twining_record
Record session actions, decisions, and discoveries to make them visible to future agents as status posts, tracked decisions, and blackboard entries.
Instructions
Record what you did, any choices you made, and anything you discovered. Call before committing or ending a session. The summary becomes a status post. Decisions become tracked records with rationale. Findings become blackboard entries visible to future agents. Scope is auto-inferred from git diff if omitted.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Area of codebase affected. Auto-inferred from git diff if omitted. | |
| summary | Yes | What you did this session — one or two sentences. Kept to 200 characters — longer text is truncated with the full text preserved in the entry detail. Lead with the most important information: similarity search weighs the opening of the text most heavily. | |
| agent_id | No | Agent identifier (default: main) | |
| findings | No | Discoveries, warnings, needs, and surprises — anything the next session would want to know that is not visible from the diff: odd patterns you noticed, fragile spots, dead ends you ruled out, things that did not work as expected. Prefix with "warning:" or "need:" for severity. E.g. ["Auth tokens stored in localStorage — fails SOC2", "warning: No token rotation exists", "need: Add rate limiting before launch"]. A substantial change with zero findings is usually under-recording, not a clean run. Lead each finding with the most important information — the first ~200 characters carry the most weight in similarity search. | |
| resolves | No | Blackboard entry IDs (needs/questions/warnings from twining_assemble or twining_triage) that this session's work handled — they are marked resolved and leave the open lane, and the status post back-references them | |
| decisions | No | Choices you made. Each item is either a natural-language sentence ("Chose X over Y — reason") or a structured object ({ summary, rationale, alternatives: [{ option, reason_rejected }] }) when the content is too long or too structured for the NL parser to split cleanly. | |
| depends_on | No | IDs of prior decisions that your decisions depend on (from twining_assemble or twining_why output) | |
| reversible | No | Whether your decisions are easily reversible (default: true) | |
| supersedes | No | ID of a prior decision that your work replaces or invalidates. Requires exactly ONE decision in this call — with multiple decisions the superseding record is ambiguous, so the supersession is SKIPPED and reported (supersedes_skipped). A target id that does not exist is also reported (supersedes_dangling), not silently ignored. | |
| assumptions | No | Conditions your decisions depend on. E.g. ["Data is relational", "No strict ordering required"] | |
| commit_hash | No | Git commit hash to associate with these decisions | |
| constraints | No | What limited your options. E.g. ["Must support Node 18+", "Cannot add new dependencies"] | |
| affected_files | No | File paths you changed or that are affected by your decisions | |
| affected_symbols | No | Function/class/method names affected by your decisions |