design: convention over configuration as a directive principle — opinionated defaults, escalate to human rather than flail

[visionik]

Context

@quinnypig's agent-native cloud spec (https://x.com/QuinnyPig/status/2055497559813304735) closes with:

"AWS forces explicit decisions on 1000 things with 1 obviously right answer 95% of the time. The agent-native platform should have brutal opinions about defaults, and when it needs to ask, ask the human, not flail through alone."

Directive has setup interviews, configurable strategies, and many options — but no explicit principle requiring opinionated defaults or specifying when to escalate to a human vs. when to just decide. The autonomy level work (#1162) captures whether to act; this is the complementary question: what to decide when acting without asking.

The design question

Should directive adopt "convention over configuration" as a named design principle, and if so, where does it apply?

Candidate applications within directive

1. deft-directive-setup interview design

Currently the setup interview asks many questions. The "convention over configuration" principle says: have a strong default answer for every question, show it to the user, and only ask when the default would be materially wrong for their context. This would compress the interview significantly and reduce the number of uninformed choices agents make when users give vague answers.

Concretely: what are directive's opinionated defaults for strategy (interview), coverage threshold (85%), branching (feature branches), and the new autonomy level (#1162) and delegation boundary (#1160)? Are they documented as defaults, or discovered by reading the skill?

2. deft-directive-build mid-implementation decisions

When an agent hits an ambiguous decision during implementation (two valid architectural approaches, unclear scope boundary), the current behavior is unspecified. "Convention over configuration" says: have an opinionated answer ready, apply it, and surface what you chose to the human rather than stopping to ask. Only escalate when the decision has material consequences the human should own.

3. Task design

Tasks should have opinionated defaults for all parameters. When a parameter is missing and the default is obvious, use it silently. Only surface missing parameters when the default would be wrong more than ~5% of the time.

The harder question

"Convention over configuration" and "ask the human when uncertain" (#1162 conservative autonomy) can be in tension. If the agent has an opinionated default, should it apply it silently or show it? If it shows it, is that still "convention over configuration" or is it just a pre-filled question?

The resolution might be: apply the default and report what you did (Fail Loud applies here too — don't hide that you made a choice). That's different from asking before acting.

Related

• feat(agents,setup): configurable agent autonomy level — default to analysis/plan, mutate only when explicitly requested or autonomy permits #1162 (configurable autonomy level — when to act vs. ask; this is about what to decide when acting)
• feat(setup): add delegation-boundary questions to deft-directive-setup Phase 2 #1160 (delegation boundary in setup — applies the convention to autonomy scope defaults)
• feat(coding): errors as instructions — agent-actionable error output as a named coding standard #1171 (errors as instructions — the complementary principle for when things go wrong)

Low-priority design question for now — the setup interview redesign and build-phase decision rules are the most concrete implementation surfaces.