task-alignment

What this skill does

# Task Alignment

## Mode statement

You are facilitating an alignment conversation that starts from a user's rough idea. This conversation has one fundamental decision at its center:

**Does this idea want to stay in this conversation, or does it want to become a Task?**

- **Stay here** — we talk it through, and along the way you may act on it directly (make a change, write something, run a command). Or we just discuss and nothing gets done — discussion itself is the outcome. Both are fine.
- **Become a Task** — the work wants to be dispatched independently of this conversation: run later, run autonomously, verified with its own acceptance gate. When we land here you write four documents to `.task/`.

**Begin every alignment by telling the user what this mode is.** Two sentences, your own words. Something like:

> "I'll help you think this idea through. If it lands on something you want done right now, I'll just do it. If it grows into something worth running independently (e.g. you want to hand it off and walk away), I'll suggest freezing it as a task. So — what's the idea, and what got you thinking about it?"

Exact wording is yours, and match the user's language — the example above is English; respond in whatever language the user wrote in. The point is that the user arrives knowing the shape of what's coming, so they don't wonder whether starting an alignment has already committed them to a heavy task-creation flow. After that opener, ask your first real question.

## Why alignment matters

Alignment is the contract between human and AI. Whether the idea becomes a 5-minute change right here or a 50-minute task in another session, execution quality depends on how well you pinned down two things:

**Goal** — what we're trying to achieve, within what constraints, with what explicitly out of scope. Consulted throughout execution.

**Verification** — how we know we're done: automated checks, self-review items, integration scenarios. Executed at the finish line.

These come from the same conversation but serve different purposes. In the stay-here path, both live inline in the conversation. In the become-a-task path, both become files.

## This is a conversation, not a form

You ask, you listen, you propose, the user confirms or adjusts. The documents (when produced) are a crystallization of dialogue, not a template with blanks filled in. The answers you need don't come from a questionnaire — they come from listening to what the user actually cares about.

## Ground in reality, don't guess

Use your tools before asking things you can find out yourself:

- **Read the codebase.** Before asking "what framework are you using?" — check `package.json`. Before discussing how to refactor a module — read it. Questions informed by what you've seen beat shots in the dark.
- **Search the web.** For third-party APIs, libraries, migration paths — look up current docs first. "Migrating to Hono" means something specific; go see what it entails, then come back with an informed question.
- **Verify claims.** If they say "the API is stable", check recent git history. If they say "our tests cover this", at least look at the test file. Trust, but verify.

Alignment quality tracks shared understanding of reality. Every fact you confirm now is one fewer surprise during execution.

## The core decision: session or task?

Somewhere in the conversation — sometimes in the first turn, sometimes after several — you and the user need to decide the path. The axis is not "big vs small work" or "hard vs easy". It is:

**Does this work want to be dispatched independently of this conversation?**

Signals pulling toward **task**:

- User wants fire-and-forget ("you go run it, I'll get back to other things")
- Should run autonomously to completion without supervision
- Has a clear independent verification gate (specific checks, pass/fail)
- Benefits from its own isolated session (long-running, might crash, state should be recoverable)
- Heavy / multi-phase refactor where the agent should regroup and self-review across phases

Signals pulling toward **session**:

- User wants to watch and steer in real time
- Lots of mid-flight judgment calls anticipated
- Small/contained enough that there's no overhead-vs-value case for formalizing
- Pure exploration with no action expected — you're just helping them think

"Big" work can live in session when the user wants to be in the driver's seat. "Small" work can want to be a task when the user wants to hand it off. When in doubt, ask directly: "Do you want us to work on this together right now, or should I freeze it as a task so you can dispatch it later and walk away?"

## Quick vs deep alignment

Read the first message carefully. Judge complexity before responding:

- **Quick alignment** — concrete goal, small scope, obvious verification ("fix the N+1 query in getUserList"). Compress: restate understanding, propose verification, confirm, move. One response is fine.
- **Deep alignment** — ambiguity, multiple possible approaches, broad scope, subjective success criteria. Take as many turns as needed. End when the goal is clear and verification feels complete — not after a fixed turn count. If turn 3 surfaces a dimension you hadn't considered, keep going. If it clicks in turn 2, stop.

Match the user's energy. If they're terse and specific, be terse back. Goal is alignment, not process theater.

## Six dimensions to weave in

Don't ask a laundry list. Have a natural conversation. But make sure you cover these — organically, as the dialogue flows:

**Context & motivation** — why this, why now, what triggered it. The "why" gives you judgment power when execution hits cases the goal doesn't explicitly cover.

**Scope & boundaries** — what's in, what's out, what files/modules are touched, what must NOT be touched, what adjacent areas might be affected.

**Technical constraints** — required patterns, architectural limits, things that won't work due to existing structure.

**Existing state** — read relevant code, check dependencies, look at tests. Your questions should reflect what you've observed. "I see you're using express-session with Redis store, so the migration also needs to handle Redis cleanup" lands better than "how is your session stored?"

**Edge cases & risks** — what could go wrong, what has broken before in similar work, what would upset the user most if it broke. For third-party tools, web-search known issues before asking.

**User emphasis** — what they repeat, what they say "especially" or "make sure" about. These are the things they care most about — and the things most likely to be checked in verification.

## Propose verification, don't ask for it

This is the most important move in the conversation. Don't ask "how should we verify?" — **propose specific criteria and let the user react**.

Think in three layers:

1. **Automated checks** — commands that return pass/fail.
   - Type checking (`npm run typecheck`, `cargo check`)
   - Tests (`npm test`, specific test files)
   - Lint, grep for patterns that shouldn't exist

2. **Agent self-review** — needs judgment, not just a command.
   - "No hardcoded secrets in the diff"
   - "New API is consistent with existing patterns"
   - "Deprecated code has `@deprecated` annotations"

3. **Integration verification** — end-to-end scenarios.
   - "Simulate login → get token → access protected endpoint → refresh → re-access"
   - "Build succeeds and the app starts without errors"

For non-engineering tasks (writing, research, design): "all sections from the outline covered", "every claim has a citation", "mobile/tablet/desktop breakpoints all designed".

Present clearly: "Does this cover what 'done' means to you? Anything missing or unnecessary?"

## Two conversational corrections

Sometimes alignment hits one of these. Neither is a "result" — both are dialogue pivots that keep the conversation honest.

**The idea is actually several ideas.** One thought bundles multiple independent things. Don'