preparing-a-yak

Preparing a Yak

Overview

Preparing a yak turns a vague idea into a buildable spec with sub-yaks. Each phase stores its output on the yak itself using yx commands, so everything travels with the yak.

Yaks come in different flavours. A feature adds or changes observable behaviour. A refactoring changes structure while preserving behaviour. A chore is everything else (dependency upgrades, CI fixes, tooling). The preparation flow adapts to the type.

When to Use

• Yak exists but has no context, or context is vague
• Before picking up a yak for implementation
• When a yak needs requirements fleshed out before coding

Don't use when:

• Yak already has context, examples, and sub-yaks
• Yak is a simple, obvious task (just pick it up)

Phase 0: Read Existing State

Before doing anything, understand what you're working with:

1. Read the yak's current state:

   yx context --show "yak name"
   yx field --show "yak name" examples
   

2. Read parent and sibling yaks for scope and constraints:

   yx ls
   

3. Explore relevant code — read the files and tests that this yak will touch. Ground yourself in the codebase before brainstorming.

Skip phases that already have approved content. If the yak already has a solid spec in context, go straight to Phase 2.

Phase 1: Mark the Yak as WIP

Before doing any visible work, claim the yak:

yx state "yak name" wip

Preparation is active work. Other agents and the human need to see that this yak is being worked on.

Phase 2: Brainstorm the Spec

Use /brainstorming to explore the idea collaboratively with the user.

Adaptation: Instead of writing the spec to a file, store it as the yak's context:

cat <<'EOF' | yx context "yak name"
# Goal
[What this yak accomplishes]

# Type
[Feature | Refactoring | Chore]

# Success Criteria
[Specific, testable criteria]

# Design Decisions
[Key decisions from brainstorming]

EOF

Done when: The user approves the spec in context, and the yak's type (feature, refactoring, or chore) is clear.