# Tracker — Data Gathering Rules

Reference for the agent-dashboard `.agent-status/tracker.csv` + the dashboard HTML pages. To be promoted to a `/tracker` skill later.

## Status taxonomy

Valid `Status` values (workflow stages left → right). Linear-state mapping shown.

| Dashboard Status | Linear State | When |
|---|---|---|
| **Backlog** | Todo | User has moved a Linear-backlog ticket to Linear-todo. We track it. No agent assigned, no probing yet. |
| **Todo** | In Progress | We've picked it up at the user's request. No comments / probing yet. Agent starts analyzing + evaluating. |
| **Ready** | In Progress | Probing complete — BE response checked, Figma extracted, ambiguity resolved, not blocked. Ready for user to greenlight pickup. |
| **In Progress** | In Progress | User asked us to pickup the Ready ticket. We're actively iterating on PR. |
| **Need Attention** | In Progress / any | PR open OR Linear In Progress that has SOMETHING pending user's decision before continuing. MUST document what user needs to do (in the MD doc). |
| **Review** | In Progress | In babysit-CR loop OR explicitly parked for stakeholder review. |
| **Done** | Done | PR merged AND deployed to staging. Auto-archives after **3 working days**. |
| **Dropped** | Cancelled | Cancelled / superseded / out of scope. |

**Ignored entirely:** Linear `Backlog` state — user moves these to `Todo` first before they appear in the dashboard.

## Workflow

The user's only Linear action is **Backlog → Todo**. Everything else (Todo → In Progress → Done) is dashboard-driven and we auto-update Linear to match:

1. User moves Linear ticket Backlog → Todo. **We add it to dashboard `Backlog`.**
2. User says "pickup ticket X" → **we set Linear In Progress + assign to user**, **dashboard moves to `Todo`**, agent starts probing/analyzing.
3. When analysis complete + context clear → **dashboard moves to `Ready`**. Wait for user pickup.
4. User says "pickup Ready ticket X" → **dashboard moves to `In Progress`**, agent iterates on PR.
5. User says "flip + babysit" → **dashboard moves to `Review`**, babysit-CR loop runs.
6. PR merges + staging republished → **dashboard moves to `Done`**.

### Assignee rules

- A Linear ticket in `Todo` state may be assigned to user OR to Ibra (or anyone else).
- When the user asks to pickup a ticket: if it's assigned to **user**, proceed (set Linear In Progress, dashboard Todo).
- If the ticket is currently `In Progress` in Linear AND assigned to **Ibra** (or another teammate): **DO NOT TAKE IT**. Inform the user ASAP — surface the conflict, ask for direction.

## Need Attention requirement

Whenever a ticket moves to `Need Attention`, the agent MUST write a markdown doc in `tickets/<TICKET-ID>/` describing:
- What's pending
- What user needs to decide
- Options + agent recommendation

The `MD` CSV column points to this primary doc. The dashboard shows it as a `⚠ See:` link on the card.

## Sources for the CSV

1. **Linear tickets** — state.type in {`unstarted` (Todo), `started` (In Progress)} only. Skip `backlog`, `completed`, `cancelled`, `duplicate`.
2. **Open PRs** — `gh pr list --state open` on both `NanoStreetApp/mobile` and `NanoStreetApp/backend`. May reference 0..N Linear tickets via branch/title/body.
3. **Worktrees** — `.claude/worktrees/<name>` directories. Captures agent name (worktree basename), host (local / sg-dev), tmux window number.
4. **MD docs** — `.agent-status/tickets/<TICKET-ID>/*.md` and `.agent-status/prs/pr-<N>/*.md`.

## Multi-ticket PRs

One PR may bundle multiple Linear tickets. Each ticket gets its OWN CSV row, but they all share the same `PR` value (e.g. `#382`).

PR-wide docs (acceptance criteria, test checklist) live in **one canonical location**: `.agent-status/prs/pr-<N>/`. Per-ticket folders only carry ticket-specific findings (e.g. backend probe results, Figma specs, architectural plans).

## Folder structure

```
.agent-status/
  dashboard.html              # Main board (groups by status)
  ticket-detail.html          # Single-ticket detail view
  tracker.csv                 # Source of truth
  tracker-rules.md            # This file
  tickets/
    NAN-XXX/
      *.md                    # Per-ticket findings, plans, probes
  prs/
    pr-<N>/
      acceptance-criteria.md  # What "done" means (defined when picking up)
      test-checklist.md       # Device-verify steps (evolves as scope grows)
      bundled-tickets.md      # If PR covers >1 ticket
      *.md                    # PR-specific findings
```

## CSV schema

```csv
Ticket,Title,Status,Linear Status,Assignee,PR,PR Status,Page / Tab,Linear URL,Agent,Host,Window,MD,Preview,Notes
```

Field rules:
- `Ticket` — Linear ID (NAN-XXX). May append " (Bug N)" for sub-bug differentiation.
- `Title` — short human readable.
- `Status` — one of: Backlog | Todo | Ready | In Progress | Need Attention | Review | Done | Dropped.
- `Linear Status` — raw Linear state (Todo / In Progress / Done / Cancelled).
- `Assignee` — "You" | full name (e.g. "Ibra") | "Unassigned".
- `PR` — "#382" or "#375 / #378" for multi-PR. Empty if no PR yet.
- `PR Status` — DRAFT | CR | APPROVED | MERGED | BLOCKED.
- `Page / Tab` — UI surface, e.g. "Stock Detail — Financials".
- `Linear URL` — full https://linear.app/... link.
- `Agent` — tmux window/worktree name.
- `Host` — "local" | "sg-dev".
- `Window` — tmux window number.
- `MD` — primary doc path (for Need Attention). Relative to .agent-status/.
- `Preview` — full deep-link, **percent-encoded inner URL**, scheme `nanostreet-dev://` (bundle-specific — dev bundle only; generic `exp+nanostreet://` is ambiguous when both dev + preview bundles are installed). Template: `nanostreet-dev://expo-development-client/?url=https%3A%2F%2Fu.expo.dev%2F5fff892f-218c-4b1c-bd29-bf8b0551d675%3Fbranch%3Dpr-N%26runtime-version%3D1.0.1`. The EAS hook comment posts the generic `exp+nanostreet://` form — copy the encoded URL portion from it via `gh pr view <N> --comments`, then swap the scheme prefix to `nanostreet-dev://`.
- `Notes` — short context.

## Render rules

### dashboard.html (board view)

Top row (left): `NAN-XXX | Linear Status (Assignee)`.
Top row (right): `host:window` chip + PR pill with status icon.
Middle: Title, then `Page / Tab · Agent`, then Notes.
Bottom L1 (only when `Need Attention` AND `MD` set): `⚠ See: <MD link>` opens markdown viewer.
Bottom L2 (only when `Preview` set): branch-name text + 📱 open + 📋 copy.
Bottom L3 (always): `View →` link to `ticket-detail.html?ticket=<ID>` (same tab).

### ticket-detail.html

URL: `ticket-detail.html?ticket=NAN-XXX`

- Header: ticket id + Linear status + assignee + Linear link
- Status pill + PR pill (with status icon)
- Title + Notes
- Sidebar (or top picker on mobile): list of all `.md` files in `tickets/NAN-XXX/` AND in `prs/pr-<N>/` if PR exists
- Main: markdown viewer (renders selected file with tables + mermaid)
- Back link to dashboard
- Same-tab navigation so browser back/forward works

## Auto-archive rule

Tickets in `Done` status auto-hide from the default dashboard view after **3 working days** since the merge date. Show via a toggle / filter if needed for historical reference.

## Skill behavior (when promoted)

When `/tracker` runs:
1. Fetch Linear In Progress + Todo for the team (skip Backlog state).
2. Fetch open PRs from mobile + backend repos.
3. Scan `.claude/worktrees/` for active agents.
4. Scan `.agent-status/tickets/*` and `.agent-status/prs/*` for docs.
5. Cross-correlate Ticket ↔ PR ↔ Worktree ↔ MD.
6. Derive `Status` per the workflow rules above.
7. Update Linear state if dashboard transition implies it (Todo → In Progress + assignee = user).
8. Auto-archive `Done` rows older than 3 working days (move to archive section or drop).
9. Preserve user-edited Notes column (merge by Ticket id key).
10. **Rsync the local `.agent-status/` → `sg-dev:/srv/agent-dashboard/`** so the live dashboard (https://dash.devbox.nararya.id/dashboard.html, also a Telegram Mini App) reflects the new CSV + any newly created tickets/<ID>/ or prs/pr-<N>/ docs.

```bash
rsync -av --delete \
  --exclude '.DS_Store' --exclude '*.swp' \
  --exclude 'HANDOVER-DASHBOARD-MIGRATION.md' \
  /Users/fathoni/Documents/Project/BlockDev/nano-street/mobile/.agent-status/ \
  sg-dev:/srv/agent-dashboard/
```

## Live dashboard

- URL: **https://dash.devbox.nararya.id/dashboard.html** (Caddy on sg-dev, Let's Encrypt cert, GCP VPC firewall open)
- Mirrors `mobile/.agent-status/` via the rsync step above
- Telegram Mini App URL points here
- Local Tailscale fallback (https://fathoni-m1pro.saga-altair.ts.net/) remains until BotFather URL swap is done

## Out of scope for this skill
- Auto-spawning agents.
- Auto-creating Linear tickets (per existing `feedback_no_auto_linear_ticket_create.md`).
- Auto-flipping PRs ready or auto-merging.
- Taking tickets currently assigned to Ibra (in Linear `In Progress` state) — must inform user first.