# Tutorial — running your first Heliostat cycle

A full pass through the phases — Pitch, Commit, Build, Cooldown — wiring a GitHub repo so commits auto-link to scopes. Roughly 15 minutes of setup; the rest is whatever cycle length you pick.

## Prerequisites

- A GitHub account (recommended; works without one but you lose auto-link)
- One feature idea you've been wanting to ship

## Steps

### 1. Think — capture loose ideas

Go to `/think`. Create a few notes about your idea — separate ones for the problem, what you'd build, things you're unsure about. Connect related notes with `[[wikilinks]]`. Add `#tags` if you have multiple themes.

When a cluster feels coherent, select the notes and click **Extract** — Heliostat hands them to OpenAI and seeds a draft pitch.

### 2. Pitch — shape the work

Open `/pitch` and edit the draft (or create one from scratch). Fill in:

- **Title** — keep it specific
- **Size** — T-shirt size, S/M/L/XL. This is your *appetite*, not an estimate. M = 1–2 weeks of work.
- **Problem** — what's actually wrong
- **Solution** — sketch, not a spec
- **Rabbit holes** — what you'll consciously not do
- **No-gos** — what's explicitly out of scope

Ask the Senior to review. It pushes back on vague pitches — better now than after you've started.

When happy, mark the pitch **Ready**.

### 3. Commit — start a cycle

On `/commit`, pick the pitch(es) you'll ship and start a cycle. For each pitch you commit, define one or more **scopes** — independent slices of work you can finish on their own. Tag each scope with a short token (e.g. `auth`, `billing`). That token is what links commits to the scope.

Default cycle is 2 weeks. Pick longer (up to 6) for L/XL pitches.

### 4. Build — track on the hill chart

`/build` is your home for the cycle. Each scope sits on the hill at a position 0–100:

- **0–50 (up-side)** — figuring out the work
- **50–100 (down-side)** — executing

Record check-ins as you make progress. The hill chart's job is to answer "do I know what I'm doing yet?" not "what % done?".

#### Auto-link commits

If you connected a GitHub repo, commits whose branch name or message contains a scope tag auto-create check-ins. Branch `auth/login-flow` shows up on the `auth` scope. Commit message `[auth] fix CSRF` does the same.

#### Log unplanned work

When something pulls you off the plan, log it. Don't replan the cycle. Commits that don't match any scope tag get auto-classified as unplanned and grouped by branch.

### 5. Cooldown — clean up and reflect

When the cycle ends, `/cooldown` opens up. Three things to do:

1. **Cleanup tasks** — small maintenance work
2. **Idea capture** — brain-dump cooldown ideas
3. **Retro** — the Retro Coach walks you through what shipped, what got cut, what surprised you

Cut scopes go back to the pitch list as drafts. Lessons captured in the retro carry forward to future cycles.

---

See [/methodology.md](/methodology.md) for the philosophy behind the phases, or [/faq.md](/faq.md) for specific questions.