twining-decide

Twining Decide — Decision Recording

You've made (or are about to make) a significant technical choice. Record it so future sessions and agents can understand what was decided, why, and what alternatives were rejected.

Which tool to call. twining_record is on the default tool surface and routes decisions to the same decision store as twining_decide. twining_decide and the decision-lifecycle verbs (twining_link_commit, twining_override, twining_reconsider, twining_promote) exist only when the project sets tools.full_surface: true in .twining/config.yml. Use twining_record unless you have confirmed the full surface is available — it works everywhere.

When to Invoke

• After choosing between architectural alternatives (e.g., REST vs gRPC, PostgreSQL vs MongoDB)
• After making implementation choices with tradeoffs (e.g., caching strategy, error handling approach)
• When the user says "let's go with", "I've decided", or makes an architectural choice
• After resolving a design question with alternatives considered
• NOT for trivial choices (variable names, formatting, simple config values)

Workflow

1. Identify the Decision Scope

Use the narrowest path that covers the affected area:

• "src/auth/" for auth-related decisions
• "src/database/schema.ts" for a specific file
• Never "project" unless it truly affects everything

2. Record the Decision

Call twining_record with a summary of what you did and a decisions array. Each entry is either a natural sentence — "Chose JWT over server-side sessions — stateless auth survives horizontal scaling" — or a structured object when the content is too long or too structured to split cleanly:

• summary: One-line statement of the choice (e.g., "Use JWT for stateless authentication")
• rationale: Why this option was chosen. Give the actual reasoning. If your rationale merely restates the summary, the record captures the WHAT and loses the WHY — which is the entire reason this system exists.
• alternatives: At least one rejected option with option and reason_rejected, optionally pros/cons
• context: What situation prompted this decision
• confidence: high (well-researched, proven), medium (reasonable, some uncertainty), low (best guess, needs validation)
• domain: e.g. architecture, implementation, testing, deployment, security, performance, api-design, data-model — inferred from content when omitted
• constraints / assumptions: What limited the options, and what you're treating as true