wt-writing-tasks

WT Writing Tasks

Write each TaskDocument body as an implementation-grade plan the launched agent can execute without rediscovering the work. The agent starts in a fresh worktree with zero conversation context; the body is its only guaranteed input. Spec files support the body, they do not replace it.

Canonical location

• The TaskDocument body at <repo-root>/.wt/execution/tasks/<slug>.toml is the canonical home of implementation steps.
• The spec's 03-Architect/07-tasks.md keeps the slice graph only: slice titles, dependencies, parallel groups, execution shape, and the path of each TaskDocument. Do not duplicate step detail there.
• The body may reference planning/specs/<slug>/ files for rationale and durable contracts, but the agent must be able to execute from the body alone.

Body structure

Top-down order. The agent reads top-down and often acts before reaching the end, so constraints come before context, and context before steps.

1. ## 계획 (Planning) — slice metadata from wt-ready: 유형 (type), 예상 소요 (expected duration), 예상 근거 (estimate basis), 권장 watch cadence (suggested watch cadence), 막힘 / 의존성 (blocked by), 실행 형태 (execution shape), 크기 (size class), 확인 방법 (acceptance checks). Prefer Korean human-facing labels with the stable English key in parentheses.
2. ## 필수 준수 (Hard constraints) — within the first ~30 lines of the body. Design language rules, security envelope, cross-cutting prohibitions, and base-branch restrictions, each with the canonical spec/contract path so the agent can pull detail without scrolling. Background: empirically (.wt/planning/specs/wt-studio-authoring-surface/04-Feedback/10-retrospect.md), constraints buried in the lower half of a long body are silently dropped by the first agent turn even when the spec fully states them; top-of-body placement is the cheap structural fix. Omit the section only when the slice genuinely has no such constraint.
3. ## 맥락 (Context) — one-line goal, verified evidence with file:line or command output, and spec references by relative path.
4. ## 작업 (Tasks) — implementation-grade tasks, the core of this skill.

Task structure

Every task declares its files first, then bite-sized checkbox steps. One step is one action (2-5 minutes).

### Task 1: <component>

**Files:**
- Modify: `src/cli.rs` (ProfileCommand enum)
- Modify: `src/commands/profile.rs:12-40`
- Test: `tests/profile_list.rs` (create)

- [ ] Step 1: 실패 테스트 작성

```rust
#[test]
fn profile_list_orders_valid_profiles_by_name() {
    let ws = TestWorkspace::with_profiles(&["beta", "alpha"]);
    let out = ws.run_wt(&["profile", "list"]);
    assert!(out.status.success());
    assert_eq!(out.stdout_lines(), vec!["alpha", "beta"]);
}
```

- [ ] Step 2: 실패 확인

Run: `cargo test profile_list_orders_valid_profiles_by_name`
Expected: FAIL — clap rejects `list` as an unrecognized subcommand

- [ ] Step 3: 구현 (계약)

- `src/cli.rs`: add a `List` variant to `ProfileCommand` with `long_about`
  describing the inventory contract.
- `src/commands/profile.rs`: route `ProfileCommand::List` to the existing
  `list(ctx)`; do not change its output shape.
- Read inventory via `Config::load_profile_inventory`, not `load_profiles`,
  so invalid profiles surface as warnings instead of failing the list.

- [ ] Step 4: 통과 확인

Run: `cargo test profile_list_orders_valid_profiles_by_name`
Expected: PASS

- [ ] Step 5: 커밋

```bash
git add src/cli.rs src/commands/profile.rs tests/profile_list.rs
git commit -m "feat: add explicit wt profile list command"
```

Adaptive code level

• Test code is complete. The failing test is the acceptance instrument; a contract-shaped test cannot fail meaningfully. Write the real assertions with realistic data.
• Implementation is a contract, not a code dump: exact file paths, the symbols to add or change, signatures, and behavior rules. The launched agent is a full agent with repo access — it writes the code; the body pins what the code must satisfy.
• Every symbol the contract names must either already exist in the repo (verify with grep/read while authoring) or be defined by an earlier task in the same body.

For non-code slices (docs-only, config, prototype), keep the same skeleton and swap the instrument: the "test" becomes the observable check (rendered output, generated TOML, command transcript) and "implement" becomes the authoring contract.

No placeholders

These are plan failures; never write them in a body:

• "TBD", "TODO", "decide later", "handle appropriately", "handle edge cases"
• "add tests" without the actual test code
• "same/similar to Task N" — repeat the contract; the agent may read out of order
• a step that says what to do without how (code, contract, or command required)
• a Run: command without its expected outcome
• a referenced type/function/path that no earlier task defines and the repo does not contain
• hedged file lists ("expected files to change", "likely involved") or unresolved alternatives ("src/lib.rs or src/commands/task.rs") — read the repo while authoring and commit to one

Self-review before handoff

Run this checklist on the finished body; fix inline.

1. Criteria coverage — when a spec exists, every EARS criterion in 02-Example/03-criteria.md maps to a task. List gaps.
2. Placeholder scan — search the body for the patterns above.
3. Symbol consistency — every referenced path/symbol verifies against the repo (grep -rn "<symbol>" src/) or an earlier task; names match across tasks exactly.
4. Body order — hard constraints appear within the first ~30 lines.
5. Command check — every Run: line is executable verbatim from the worktree root, and the 계획 acceptance checks match commands the steps actually run.

Rationalizations

Excuse	Reality
"The agent reads the repo, so paths can be omitted"	Path exploration is the first entry point for drift. It takes 10 seconds to write the path, and if the agent looks in the wrong place, you lose a turn.
"Write the file list as 'likely' and let the agent decide the placement"	Files is a finalized list. If there are two alternatives, read the repo during prep and decide on one. Delegating decisions is delegating drift.
"If the implementation is the contract, the tests being the contract is enough"	Tests are the acceptance criteria themselves. If they are not complete, no one knows what passing is.
"An example output shape 'like ~' is enough"	Pin the contract exactly. Markings like "same/similar" are read as a signal that variations are allowed.
"Since the body is getting long, replace it with a spec reference"	References are supplementary. The agent must be able to execute from the body alone.
"It's a small slice, so step decomposition is overkill"	Even for small, the skeleton of confirm failure → implement → confirm pass → commit is maintained. Only the number of steps decreases.
"You only know the expected output by running it"	Then run it now during prep to confirm. What is forbidden is writing guessed output.

Red flags — stop and fix the body

• A task with no Files list
• A test step written in prose instead of code
• Delegation sentences like "the agent will handle the implementation"
• Acceptance checks that no step actually runs
• Hard constraints below the fold