Aporia session notes

A coding session is one of the two ways the product changes (the other is an Aporia Session with the team). The code iterated; along the way you decided things, hit open questions, and sometimes deviated from the intent you were given. That reasoning is exactly what normally evaporates into the diff. This skill writes it back onto the map, attached to the parts it's about, for the team to curate.

You reach Aporia through the MCP server only. It's pinned to one product; you never pass a product id. Call the tools fully-qualified as tools of the aporia MCP server (e.g. aporia:search_graph) so they resolve even when other MCP servers are connected. If the tools aren't available, tell the user to configure the Aporia MCP server first.

The hard line

Never fabricate rationale. If the why behind a choice wasn't actually established in the session, it is an open question, not a decision. Every note must trace to a real moment in this session — something decided, asked, or observed-as-diverging. No invented confidence.

The routing rule — item vs comment vs correction vs PR body

Not everything a session produces deserves a new item. Route by two questions, in order — does this owe a human a verdict, or a unit of work? and, if so, is that human in this session right now?

• Ask, first — when a human is working with you and the verdict is theirs to give, put the question to them instead of filing it. An item addressed to someone who is already reading your output is the slowest possible way to ask them; they answer in a sentence, and what you record is a decision — worth more to the map than an open question ever was. This is the default in an interactive session, not an optional shortcut. File instead when they defer it, decline to settle it now, say it needs someone else, or when the answer must outlive the session as a standing constraint. Running unattended — a scheduled sync, a CI run, a background agent with nobody to ask — there is no one to put it to, so file.
• A new item (aporia:record_notes) — when it owes a verdict and asking is not available or not enough: an open question someone must answer, a tension to adjudicate, a decision made, a bug/task to build. An item is a triage row a human must process; over-filing buries the verdicts the team actually owes. The tell that you have over-filed: you could have gotten the answer in the time it took to write the body.
• A comment (aporia:comment_item { ticket, body }) — context on an existing item: progress while working it, evidence you gathered, a premise the code now contradicts, "while working ticket 8 I noticed…". A comment is non-triageable by construction — no ticket number, no status — it lands in the item's thread and exerts zero inbox pressure. Never mint a new item to mirror or annotate one that already exists.
• A correction (aporia:update_item { ticket, body }) — when an open item's own text has gone wrong, not merely incomplete. The classic case: a decision whose core call still stands, but whose implementation line names a module, path or service the code no longer uses. Fix the text so the next reader gets the current truth, and leave a comment saying why it moved. body and rationale overwrite — restate everything still true, and write the correction in the item's own voice rather than bolting a changelog onto the end.
• The PR body — ephemeral narration of a diff (what you changed, how you tested). It belongs with the code review, not in Aporia at all.