Engineering Decision Trace Writer

Repeatedly explaining why a technical decision was made wastes time and invites the same mistakes. This skill saves settled engineering decisions as local project notes that future coding agents can use.

What it does

• Preserves reasoning: Records the problem, supporting evidence, decision, and rejected alternatives.
• Captures constraints: Keeps important user clarifications and behavior requirements alongside the decision.
• Maintains existing notes: Updates a relevant trace when its status changes instead of creating another copy.
• Supports follow-up: Identifies validation gaps, affected files, and reasons to revisit the decision.

How it works

1. Finish the review, investigation, or design discussion that establishes the decision.
2. Ask the agent to preserve it for future work, specifying a location if needed.
3. The agent checks project evidence and existing notes, then creates or updates the record.
4. Receive the file location, checks performed, and any remaining uncertainties.

Works with

Codex and local code repositories, including project instructions, Markdown documentation, code, tests, diffs, and logs. It follows the repository's existing convention for decision notes.

Why use this skill

Future agents get the reasoning behind a choice, not just the final answer. Keeping evidence and validation status together reduces repeated investigation and makes handoffs clearer.

Use cases

• Preserve a bug finding after diagnosis.
• Explain why an architecture alternative was rejected.
• Carry user-defined behavior constraints into later coding sessions.

Known limitations

Use it after a decision is settled. It does not replace the investigation itself or formal architecture documentation.