project-tracking

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, 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 a flat board (issues without parent/child relationships) and needs to be reorganized into the Epic/Story/Task hierarchy.

Step 1 — Fetch the current state

Run [migrate-fetch]. Group issues by likely level using these heuristics:

Signal	Likely level
Title starts with epic: or label type/epic or Type=Epic	Epic
Title starts with feat: or label type/feature or Type=Feature	Story
Title starts with bug: or label type/bug or Type=Bug	Bug
Title starts with chore:/task: or no prefix	Task

Step 2 — Propose the hierarchy in chat

Produce a single message:

# Migration proposal — {N} open issues

## Epics
- #10 epic: Payments & Monetization
  Will own:
    - #28 feat: Stripe integration for guide bookings
    - {other feats that thematically belong}

- #14 epic: Push Notifications & Engagement
  Will own:
    - #30 feat: push notifications (Expo / Firebase)

## Bugs (orphan — no epic owner)
- #18, #19, #20, ...
  Recommended: create epic "Stability & Bugfixes" to own all of these.
  OR leave as standalone (no parent). Pick one.

## Unclassified
- #X, #Y — could not infer parent confidently. Please tell me.

End with the same confirmation prompt as /plan-epic Step 4.

Step 3 — Apply on confirmation

For each parent → child pair, run [sub-issue link]. For issues that need an Issue Type set retroactively, run [set-issue-type]. If Issue Types are not supported, ensure the legacy type/* label is present instead.

Step 4 — Report

Print the same tree summary as /plan-epic Step 6. Save engram observation type: architecture, topic_key: tracking/{repo}/migration-{date}.

---

Flow 4: Track — Create Issues and Add to Board

Trigger model (hybrid)

Situation	Behavior
/track <description>	Create issue immediately, no confirmation
/track with multiple items or backlog session	Create all, show list, ask confirmation before executing
sdd-tasks generates tasks	Propose creating one issue per task, ask confirmation
User mentions future work ("habría que...", "falta...", "después hay que...")	Collect internally. At session end propose: "Detected N trackable items: [list]. Create as issues?"
"acordate que hay que..." / "remember to..."	Propose creating an issue immediately
Bug found during implementation	Propose creating issue with type/bug label immediately

Issue creation steps

Step 1 — Deduplicate

Run [track §1]. If a similar issue exists, show it and ask: "Issue #N already exists: '{title}'. Create a new one anyway?"

Step 2 — Create issue via MCP

Run [track §2] — mcp__github__create_issue with owner, repo, conventional title (type: description), the body template, and applicable labels. The body template lives in [track §2].

Step 3 — Add to project board

Run [track §3] (captures item_id).

Step 4 — Set project fields

Run [track §4] — load field/option IDs from engram config (tracking/{repo-name}/config), then set Status / Priority / Type.

Step 5 — Confirm to user

Created #14: feat: add OAuth with Google — added to board as Backlog/P1-High [Feature]

---

Flow 5: Query — /backlog and status questions

Default: full board summary

Run [backlog §default], then group items by Status field value. Output:

## Project Board: {project-name}

### In Progress (2)
- #14 feat: OAuth with Google [P1-High]
- #12 fix: Email validation [P0-Critical]

### Review (1)
- #13 feat: User profile page [P1-High]

### Backlog (3)
- #15 feat: Dashboard redesign [P2-Medium]
- #16 chore: Update dependencies [P3-Low]
- #17 feat: Export to PDF [P2-Medium]

### Done (last 5)
- #11 fix: Login redirect loop [P1-High]

Show statuses in order: In Progress → Review → Todo → Backlog → Done (last 5 only to avoid noise).

Filtered queries

Command	Filter applied
/backlog bugs	Only items with Type = Bug
/backlog high	Only items with Priority = P0-Critical or P1-High
/backlog in-progress	Only items with Status = In Progress
/backlog todo	Only items with Status = Todo
/backlog review	Only items with Status = Review

---

Status Transitions

Manual triggers: /track move #14 in-progress, /track move #14 review, /track move #14 done. Underlying command: [status-move].

Automatic integration points:

• Claude starts working on issue → move to "In Progress"
• Claude opens PR for issue → move to "Review" (integrates with branch-pr skill)
• PR merged / issue closed → move to "Done"

---

Rules

• GitHub Issues + Projects is the source of truth for WHAT needs to be done — backlog, tasks, stories, bugs
• Engram remains the source of truth for decisions, discoveries, and technical context — these are complementary, not competing
• Never create duplicate issues — always run gh issue list --search before creating
• Issue titles follow conventional format: type: description (e.g., feat: add OAuth, fix: email validation)
• Labels use lowercase with / separator: type/feature, priority/high, status/backlog
• Every issue MUST have at least the Type field set on the project board
• /track-init is idempotent — running it twice must not create duplicate labels or projects; handle errors from gh label create gracefully
• Project config (IDs) MUST be saved to engram after bootstrap with topic_key: tracking/{repo-name}/config
• Before any gh project item-edit call, load field IDs from engram; if not found re-derive with gh project field-list
• Batch creation requires confirmation — when proposing multiple issues at once, show the full list and wait for user approval before creating any
• Propose, don't assume type/priority — when auto-detecting trackable items from conversation, infer reasonable defaults but show them to the user before creating
• Prefer MCP for issue creation (mcp__github__create_issue) and gh CLI for all project board operations
• When /track-init has not been run (no engram config, no linked project), detect this and suggest running it before any board operation
• Fine-grained PATs do NOT support Projects V2 on personal accounts — only Classic PATs or org-scoped tokens work. When detected, offer both exits (§0-manual): recommend fixing the token (Classic PAT + gh auth, unblocks every repo) over the manual-board fallback. Never present manual creation as the only option
• gh reads its token only from GH_TOKEN > GITHUB_TOKEN (in that order), and an env var token overrides gh auth login. A correct token under any other name (e.g. GITHUB_CLASSIC_TOKEN) is silently ignored. When REST works but Projects/GraphQL returns FORBIDDEN, suspect a misconfigured env var (§0-token-env): put the Classic PAT in GH_TOKEN, verify with the one-line GraphQL viewer.projectsV2 query. Document the rule — token type, variable name, verification — never the secret value
• Both automatic and manual board creation paths converge at Step 3 (capture IDs) — the rest of the workflow is identical regardless of how the board was created
• /plan-epic is confirm-first: the full hierarchy (Epic + Stories + Tasks) is proposed as Markdown in chat; NO create_issue call fires until the user replies with an explicit confirmation keyword (dale, go, create). Anything else is treated as edit instructions, not approval.
• Issue Types are authoritative when available; legacy type/* labels are written alongside for backwards compatibility. Detect support via GraphQL issueTypes query, cache the result for the session, and fall back to label-only mode with a one-time warning when types are unsupported.
• Sub-issue links use the addSubIssue GraphQL mutation — never simulate hierarchy with text in the body ("parent: #N" alone does not create the link).
• One Task = one Claude session. If a Task does not fit in one session, it is a Story disguised as a Task — propose splitting it before creating.
• /plan-migrate never modifies issues without confirmation — same confirm-first contract as /plan-epic. Unclassified issues are flagged for the user, not auto-assigned.
• Bug issues can be standalone (no parent epic) or owned by a "Stability & Bugfixes" epic. Pick one approach per repo and keep it consistent — the choice goes into the engram config under tracking/{repo}/config.
• Body templates live in skills/project-tracking/templates/ (epic.md, story.md, task.md, bug.md) and are the ONLY source of truth for issue body structure. Do not improvise alternative formats.