project-tracking

What this skill does

**Triggers**: `/track-init`, `/plan-epic <description>`, `/plan-migrate`, `/track <description>`, `/backlog`, "qué tenemos pendiente?", "what's pending?", "acordate que hay que...", "remember to...", "vamos a planear", "armemos la épica", bug found during implementation, SDD tasks generated by `sdd-tasks`.

---

## Hierarchy model — Epic / Story / Task / Bug

This skill enforces a three-level hierarchy (plus Bug as an orthogonal type)
modeled with **GitHub Issue Types** (native) and **sub-issues** (native).
Labels are kept for backwards compatibility but Issue Types are authoritative.

| Level | GitHub Issue Type | Lifetime | Sub-issues of | Has sub-issues |
|-------|------------------|----------|---------------|----------------|
| Epic  | `Epic`           | Weeks    | none          | Stories        |
| Story | `Feature`        | Days     | Epic          | Tasks          |
| Task  | `Task`           | Hours    | Story (or Epic for hotfixes) | none |
| Bug   | `Bug`            | Hours–Days | Epic (Stability) or Story it breaks | none |

**Rules of thumb**:

- One Task = one Claude session. If it does not fit, it is a Story disguised as a Task. Split it.
- A Story without sub-issues is allowed only when its acceptance criteria already serve as the task list (truly small).
- An Epic without sub-issues is a smell — likely it is actually a Story.
- A Bug can be standalone (no parent) when it does not belong to a planned epic.

### Issue Types vs labels

The skill writes BOTH the Issue Type (when the org has Issue Types enabled)
AND the equivalent legacy label (`type/epic`, `type/feature`, `type/task`,
`type/bug`). This lets old views, filters, and the existing `/track` flow
keep working while the new hierarchy is adopted incrementally.

Detection of Issue Type availability is done once per session via the
`Issue-Type detection` block in `COMMANDS.md`. If the response is empty or the field
is unsupported, fall back to label-only mode and warn the user once per session:

> "Issue Types are not enabled on this org. Falling back to labels — `type/epic`,
> `type/feature`, `type/task`, `type/bug`. To enable native types, go to
> Org settings → Issue Types."

> **All literal `gh` / GraphQL command blocks live in [`COMMANDS.md`](./COMMANDS.md)**,
> referenced below by step ID (e.g. `[track-init §1]`). This file holds the decision
> logic; `COMMANDS.md` holds the exact invocations.

## Process

### Pre-flight: Detect Repo and Config

Before any flow, resolve owner/repo (run `Pre-flight — detect repo` in `COMMANDS.md`).
Then search engram for the project config:
- `mem_search` with query `tracking/{repo-name}/config`
- If found, call `mem_get_observation` to get project number and field IDs
- If NOT found and the flow requires project operations → warn user to run `/track-init` first

---

### Flow 1: Bootstrap — `/track-init`

Run once per repo. Idempotent — safe to run again.

#### Step 0 — Detect token capabilities

Run `[track-init §0]`. On failure, **classify the cause** using the table there —
never assume every failure is the token. Distinct causes route to distinct actions:
gh-not-authenticated (`§0-auth`), fine-grained PAT (`§0-manual`), missing `project`
scope (`gh auth refresh -s project`), a transient GitHub/network error (stop and
retry later, do NOT touch the token), or — when REST works but Projects/GraphQL
returns `FORBIDDEN` — a misconfigured token env var (`§0-token-env`: wrong token
type, or the right token under a name `gh` never reads).

**Most common (your case): fine-grained PATs do NOT support Projects V2 on personal
accounts** (only orgs). `[track-init §0-manual]` offers two exits: **fix the token**
(Classic PAT + `gh auth`, recommended — unblocks automatic creation for every repo)
or **create the board manually** (fast fallback). Recommend the token fix. If the user
fixes the token, re-run Step 0 then go to Step 1. If they create it manually, capture
the project number and skip to Step 2 (labels).

#### Step 1 — Create GitHub Project board (automatic path)

Only if Step 0 confirms Projects V2 support: run `[track-init §1]` (creates the
project + the Status / Priority / Type single-select fields).

#### Step 2 — Create labels

Run `[track-init §2]` (type / priority / status labels). Idempotent — a label that
already exists makes `gh label create` fail; catch and continue.

#### Step 3 — Capture field and option IDs

Whether the board was created automatically (Step 1) or manually (Step 0), run
`[track-init §3]` to capture `status_field_id`, `priority_field_id`, `type_field_id`
and the option IDs for each value. Required by `gh project item-edit`.

#### Step 4 — Save config to engram

Call `mem_save` with:
- **title**: "Bootstrap project-tracking config for {repo-name}"
- **type**: config
- **topic_key**: `tracking/{repo-name}/config`
- **content**: project_number, owner, repo, all field IDs and option IDs as a structured map

Confirm to user: "Board linked. Project #{project_number} for {owner}/{repo}. Config saved to engram."

---

### Flow 2: Plan Epic — `/plan-epic <description>`

Used to plan a large feature or initiative end-to-end: one Epic, its Stories,
and the Tasks of each Story. **Nothing is written to GitHub until the user
confirms explicitly.**

Run `/track-init` first if no engram config exists for this repo.

#### Step 1 — Read templates

Load the body templates from this skill directory:

- `templates/epic.md`
- `templates/story.md`
- `templates/task.md`

These are the contract — every issue created in this flow follows them.

#### Step 2 — Detect Issue Type support

Run `Issue-Type detection` (`COMMANDS.md`). Cache the result for the session.
Decide: native Issue Types mode OR label-fallback mode.

#### Step 3 — Propose the hierarchy as Markdown in chat

Produce a single chat message structured as:

```
# Epic: {Title}

Type: Epic | Priority: {P0..P3}
[Epic body following templates/epic.md]

---

## Story 1: {Title}

Type: Feature | Priority: {P0..P3} | Parent: Epic above
[Story body following templates/story.md]

### Task 1.1: {Title}
Type: Task | Parent: Story 1
[Task body following templates/task.md]

### Task 1.2: {Title}
...

---

## Story 2: {Title}
...
```

Show the full proposal in ONE message. Do not call any GitHub API yet.

#### Step 4 — Wait for confirmation

End the proposal message with EXACTLY this prompt:

```
Review the plan above. Reply:
  - "dale" / "go" / "create" → I create all N issues + sub-issue links
  - "edit <X>" / "no <X>"     → tell me what to change, I revise the plan
  - "abort"                   → drop the plan, nothing is created
```

If the user replies anything other than a confirmation keyword, treat it as
edit instructions and produce a revised proposal. Re-prompt. Never create
issues without an explicit confirmation keyword from this list.

#### Step 5 — Execute creation in order

Create issues in the order: Epic → Story 1 → Task 1.1 → Task 1.2 → Story 2 → ...

For each issue:

1. Call `mcp__github__create_issue` with title, body, labels, and Issue Type (when supported).
2. Capture the returned issue number.
3. If the issue has a parent in the proposal, link as sub-issue with `[sub-issue link]`.
4. Add the issue to the Project board (`[track §3]`).
5. Set Project fields (`[track §4]`): Status=Backlog, Priority=as proposed, Type=as proposed.

#### Step 6 — Report back

Print a single summary block:

```
## Created

Epic #N: {title}
├── Story #N+1: {title}
│   ├── Task #N+2: {title}
│   ├── Task #N+3: {title}
│   └── Task #N+4: {title}
└── Story #N+5: {title}
    ├── Task #N+6: {title}
    └── Task #N+7: {title}

Total: 1 epic, 2 stories, 5 tasks. All added to project board as Backlog.
```

Save an engram observation:

- `mem_save` with **type: architecture**, **topic_key: `tracking/{repo}/epic-{N}`**,
  content: epic title, child story+task numbers, source of the plan
  (user request, SDD spec ref, etc.).

---

### Flow 3: Plan Migrate — `/plan-migrate`

Used when an existing repo has