Skill: Intentional Design

SKILL.md

name	intentional-design
description	Use when starting a feature or facing a decision with meaningful tradeoffs -- researches options, clarifies intent, proposes approaches, and decides before any code is written. Skip for small or obviously clear changes.

Intentional Design

Overview

Think before building. Understand the problem, surface tradeoffs, pick the right approach. The output is a decision and a direction -- not a document. Hand off to intentional-development immediately after.

REQUIRED NEXT STEP: After deciding, use the intentional-development skill to execute.

When to Use

Use when:

• Starting a non-trivial feature
• Facing a choice between approaches with real tradeoffs
• Something feels unclear about the goal or constraints
• An architectural decision will be hard to reverse

Skip when:

• Bug fix with an obvious cause and fix
• Small, self-contained change (rename, config tweak, trivial addition)
• Refactor within existing established patterns
• You already know the approach and there are no meaningful tradeoffs

When in doubt: if you can write the acceptance test right now without making assumptions, skip this skill and go straight to intentional-development.

The Workflow

digraph intentional_design {
    rankdir=TB;

    start [label="Feature or decision needed", shape=doublecircle];
    research [label="Research\nCurrent patterns, prior art, constraints", shape=box];
    clarify [label="Clarify intent\n(one question at a time)", shape=box];
    clear [label="Approach clear enough\nto write acceptance test?", shape=diamond];
    propose [label="Propose 2-3 approaches\nwith tradeoffs + recommendation", shape=box];
    decide [label="Decision made?", shape=diamond];
    adr [label="Non-obvious decision?\nUpdate docs/decisions.md", shape=diamond];
    handoff [label="Hand off to\nintentional-development", shape=doublecircle];

    start -> research;
    research -> clarify;
    clarify -> clear;
    clear -> propose [label="no"];
    clear -> adr [label="yes"];
    propose -> decide;
    decide -> clarify [label="no -- more\nclarity needed"];
    decide -> adr [label="yes"];
    adr -> handoff [label="no -- code\nis clear enough"];
    adr -> handoff [label="yes -- update doc"];
}

Phase 1: Research

Before asking any questions, ground yourself in what already exists.

• Search the codebase for existing patterns related to the problem
• Identify conventions already established (naming, structure, abstractions)
• Note any constraints visible in the code (performance-sensitive paths, existing interfaces you must extend)
• Check for prior decisions in docs/decisions.md that bear on this choice

Goal: Understand the existing landscape so proposed approaches fit the codebase and don't re-litigate settled decisions.

Report findings briefly before asking questions. Don't ask about something the code already answers.

Phase 2: Clarify Intent

Ask one question at a time. Stop when the acceptance test is writable.

Focus on:

• Purpose: what problem does this solve for the user/caller?
• Constraints: performance, compatibility, reversibility, team conventions
• Success criteria: how will we know it's working correctly?
• Scope: what's explicitly out of scope?

Prefer multiple choice when the options are enumerable. Open-ended when they're not.

Stop asking when: you could write a failing acceptance test right now that would pass when the feature is done. That's the signal you have enough. Ask the minimum number of questions to reach that point -- 1-3 questions is typical. If you find yourself asking a fifth question, stop and check: can you write the acceptance test with what you already know? If yes, stop. If no, is the missing information something a spike would resolve? If yes, stop -- note the open question and move to proposals.

Do NOT ask about implementation details -- those get resolved in spikes.

Phase 3: Propose Approaches

When the approach isn't obvious, propose 2-3 options.

For each option:

• What it is (one sentence)
• Key tradeoff (what you gain, what you give up)
• When it's the right choice

Then give your recommendation with reasoning. Be direct -- don't present options as equally valid if they're not.

Option A: [name]
  Gain: faster to implement, no new dependencies
  Cost: less flexible if requirements change
  Right when: requirements are stable and simplicity matters

Option B: [name]
  Gain: handles future extension cleanly
  Cost: more upfront complexity, harder to test in isolation
  Right when: you expect this to grow

Recommendation: Option A -- YAGNI applies here. If requirements expand,
refactoring from A to B is straightforward because [reason].

Phase 4: Decide and Hand Off

Once a decision is made, stop designing and move to execution.

Do not:

• Continue refining the design after a decision
• Write implementation code or pseudocode
• Produce a spec document or implementation plan

Do:

• Confirm the decision clearly ("We're going with Option A: [brief description]")
• Note what the first spike or tracer bullet will target
• Record the decision if it meets the ADR threshold (see below)
• Say explicitly: "Using intentional-development to execute." -- this is mandatory, not optional

Do NOT ask further questions after the decision is made. If something is still unclear, it's a spike target, not a design question.

Architecture Decision Records

Write to docs/decisions.md when: a future reader of the code would ask "why did they do it this way?" and the code itself doesn't answer it.

The test: if the reasoning is visible in the code (good names, clear structure, obvious design), don't write an ADR. If the reasoning required this conversation to surface, write it.

Examples that warrant an ADR:

• Chose library X over Y (and why Y was rejected)
• Chose denormalized storage for performance reasons
• Chose not to abstract a pattern that looks repeated but isn't
• Accepted a known limitation for a specific reason

Examples that don't:

• Named a function clearly -- the name is the documentation
• Used a standard pattern from the codebase -- consistency is self-evident
• Made an obvious tradeoff with no alternatives considered

Format (keep it short -- one entry per decision, target 3-5 sentences total):

## [Topic]

[What was decided, in one sentence.]

[Why: the constraint, tradeoff, or context that made this the right call.
What was ruled out and why, if non-obvious.]

Do NOT write implementation steps, architecture diagrams, or test strategies in the ADR. Those belong in the code and its tests. The ADR records the reasoning, not the execution plan.

docs/decisions.md reflects current architecture. When a decision is superseded, update or remove the entry -- git tracks the history. Reference the file in CLAUDE.md or AGENTS.md so it loads as context in future sessions.

Common Mistakes

Mistake	Result	Fix
Skipping research, asking questions the code answers	Redundant conversation, missed constraints	Read the codebase first
Asking multiple questions at once	User answers one, you lose the others	One question per message
Proposing approaches before clarifying the goal	Options solve the wrong problem	Clarify first, propose second
Continuing to design after a decision	Scope creep, delayed execution	Decide, record if needed, hand off
Writing pseudocode or spec during design	Becomes a commitment before reality checks it	Leave implementation to intentional-development
Writing an ADR for something obvious in the code	Noise that dilutes the useful ADRs	Apply the "future reader" test
Writing implementation steps or test plans in the ADR	ADR becomes a spec doc	ADR = reasoning only; execution belongs in code
Asking questions past the acceptance test threshold	Delays execution, explores hypotheticals	Stop at 1-3 questions; spikes resolve the rest
Asking more questions after the decision is made	Never hands off	Decision made = design done; hand off immediately