twining_record
Record session activity, decisions, and discoveries for future agents. Captures choices with rationale and creates blackboard entries; scope auto-inferred from git diff.
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. | |
| 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 | |
| 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 |