chore: conciv-issue skill — backlog burndown lane methodology

.claude/skills/conciv-issue/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: conciv-issue
+description: Use when asked to pick up a GitHub issue, work the issue backlog down, burn down issues, triage open tickets, groom an issue for an agent, pick up a ticket, or dispatch an agent to fix a ticket and close it with a PR.
+---
+
+# Working the conciv issue backlog
+
+## Overview
+
+Goal: open-issue count trends to zero. The unit of work is one lane: pick one issue, groom it,
+dispatch one agent in one worktree, verify, open one PR whose merge auto-closes the issue. Never
+batch several issues into one PR, and never merge — the user merges.
+
+The orchestrator (this session) picks, grooms, verifies, and reports. Agents implement. The
+orchestrator never edits product code.
+
+## Step 0: pick one issue
+
+```bash
+gh issue list --state open --limit 60 --json number,title,labels
+```
+
+Selection order:
+
+1. `ready-for-agent` and unassigned, smallest first — pre-groomed and grabbable.
+2. Ungroomed issues with a clear defect and reproduction.
+3. Everything else needs grooming first (that grooming is itself a valid lane outcome).
+
+Skip: `agent:blocked-external`, `agent:needs-info`, `agent:in-progress`, `agent:implemented-in-pr`,
+epics/RFCs, and anything already linked to an open PR (`gh pr list --search "NNN in:body"`). If
+every remaining issue is blocked, say so and stop; do not force a lane.
+
+Lifecycle labels, transitions, and type-label grooming rules: `references/labels.md`.
+
+## Step 1: classify and groom
+
+Read the full issue and comments (`gh issue view NNN --comments`). Verify every claim in the body
+against current `origin/main` — issues go stale; file:line citations rot.
+
+Required shape before dispatch, by type: bug — RCA plan first, evidence-only Phase 1, reproduce
+before fix; no repro = comment findings, label `agent:needs-info`, next issue. Flake — same
+reproduce-before-fix bar, HARD, no exceptions. Feature/refactor — acceptance criteria enumerable as
+greps/tests; if missing, groom them into the body via `gh issue edit`. Question — answer with
+evidence in a comment, label `agent:answered`, close if resolved.
+
+If grooming reveals the issue is already fixed on main, prove it (grep/test), comment, label
+`agent:already-resolved`, close. That counts as a completed lane.
+
+## Step 2: dispatch one agent
+
+- Worktree per issue: flat name `issue-NNN` (no `+` in path), pinned base `origin/main`.
+- Agent type by shape: `conciv-frontend` (Solid/ui-kit/widget UI), `conciv-implementer`
+  (server/core, judgment needed), `conciv-mechanic` (fully-specced mechanical). Model per global
+  rules: sonnet default; opus only for adversarial review or design-heavy contract work. State the
+  model in the dispatch.
+- Dispatch is definition-of-done shaped, with the orchestrator pre-deciding the fix's design so
+  the agent never stalls on a choice. Full skeleton: `references/dispatch-template.md`.
+- Label the issue `agent:in-progress` at dispatch; run in background, no blocking waits.
+
+## Step 3: verify and hand off
+
+1. Review the agent's full diff yourself. Judge mechanism, not just correctness.
+2. Re-run gates with `--force` (turbo cache greens are claims about old inputs).
+3. Non-trivial diff → run the conciv-review skill on the branch before calling it done.
+4. Confirm PR body carries `Fixes #NNN`, CI is green, then label the issue
+   `agent:implemented-in-pr` and report the PR link to the user. The user merges; merge auto-closes
+   the issue.
+
+A full lane, checkpoint by checkpoint (including where three review rounds and one RCA earned
+their keep): `references/worked-example-316.md`.
+
+## Red flags — stop the lane
+
+- "I'll fix these three related issues in one PR" — one issue, one PR.
+- "The bug is obvious, skip the reproduction" — no repro, no fix.
+- "CI is green, I'll merge it" — user merges. Always.
+- "The issue body says the code does X" — verify against main first; bodies rot.
+- Closing an issue by hand when a PR exists — `Fixes #NNN` closes it on merge; manual close loses
+  the audit trail.
+- Working in the main repo checkout — every lane gets its own worktree.

.claude/skills/conciv-issue/references/dispatch-template.md

@@ -0,0 +1,85 @@
+# Dispatch template
+
+A definition-of-done dispatch is a fill-in template, not free text. Every section below exists to
+close one specific way lanes have gone wrong before. Fill in every section; do not skip one because
+"it's obvious" — the agent reading the dispatch has none of this session's context.
+
+## Setup
+
+Why: an agent with no worktree, or a worktree branched from a stale local `main`, produces a diff
+that can't land cleanly and wastes the whole lane.
+
+```bash
+git -C /Users/omrikatz/Public/web/aidx worktree add \
+  /Users/omrikatz/Public/web/aidx/.claude-worktrees/issue-NNN -b issue-NNN origin/main
+```
+
+- `pnpm install` in the new worktree if the lockfile changed since the last worktree was cut.
+- HARD warning to include verbatim in the dispatch: Bash cwd snaps back to the repo root between
+  tool calls — pin the absolute worktree path in every command, never rely on a prior `cd`.
+
+## The fix, decided shape
+
+Why: an agent with a genuine design choice in front of it either stalls asking for clarification
+(defeating background dispatch) or picks silently and produces a diff the orchestrator has to
+re-litigate. The orchestrator makes every judgment call before dispatch and states it as a ruling.
+
+Enumerate each ruling explicitly, e.g.:
+
+- "Use option 2 from the issue body (targeted guard in `guards.ts`), not option 1
+  (`changeset status` in CI) — rejected for its zero-changeset exit-code quirk."
+- "New state belongs in a store, not a parallel signal — see `references/labels.md` if the issue
+  touches Solid state."
+- Any file/module boundary the agent must not cross.
+
+## Constraints
+
+Repo law, restated because agents drift toward convenient defaults under pressure:
+
+- Functions, not classes. Zero comments in TS/JS. No `any`/`as`/non-null assertion/IIFE.
+- oxfmt formatting (no semicolons, single quotes, trailing commas).
+- Verify every API call against the resolved source in `node_modules` (or the package's own
+  `src/`), never guess a signature from memory or training data.
+
+## Dependencies
+
+NO new dependencies unless the dispatch names a package the USER approved verbatim. If a
+dependency seems needed mid-implementation, the agent stops and reports back instead of installing
+it.
+
+Why this rule exists: an agent's inference that "the user would probably approve this" is
+fabricated consent, not real consent — only an explicit prior approval counts.
+
+## Acceptance criteria
+
+Verbatim from the groomed issue body, each phrased so it is checkable as a grep or a test run —
+not a prose restatement the orchestrator has to reinterpret at verification time.
+
+## Gates
+
+Run from the worktree, in this order:
+
+```bash
+pnpm -C <worktree> exec turbo run typecheck --filter=<pkg> --force
+env TURBO_CONCURRENCY=1 VITEST_MAX_FORKS=1 \
+  pnpm -C <worktree> exec turbo run test --concurrency=1 --filter=<pkg> --force
+pnpm lint
+pnpm format:check
+pnpm exec fallow audit --changed-since origin/main --format json
+```
+
+- Fallow: 0 `introduced` findings. JSON runtime errors (`{"error": true, ...}`) are non-blocking.
+- Changeset decision: needed when a published package's runtime behavior changes; the
+  `check-changesets` CI gate (verify-changesets.yml) enforces coverage. If the PR intentionally
+  ships no release note (docs-only, internal tooling, a private package), apply the `no-changeset`
+  label instead of adding one.
+
+## Deliverable
+
+- Conventional commits, each ending with `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.
+- Plain push (never force-push a fresh branch that has no upstream history to protect).
+- `gh pr create` with a body that explains the mechanism of the fix (not just "fixes the bug"),
+  the exact line `Fixes #NNN`, and the Claude Code generated-by footer.
+- Never merge — the user merges.
+- Final report shape: a per-acceptance-criterion table (met / how verified), gate command outputs,
+  commit SHAs, and any deviations from the dispatch with a one-line reason each.

.claude/skills/conciv-issue/references/labels.md

@@ -0,0 +1,49 @@
+# Labels
+
+Verified against the live label set (`gh label list --limit 60`) as of this writing. If a label
+referenced here is missing, re-run that command — labels do drift.
+
+## Lifecycle labels
+
+The nightly issue tracker and the conciv-issue lane both read and write these. `agent:*` labels
+plus `ready-for-agent` and `agent-triaged` track where an issue sits in the pipeline.
+
+| Label                     | Meaning                                                              | Who sets it                                | What the lane does on seeing it                                                        |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `agent-triaged`           | Nightly issue tracker has investigated this issue.                   | Nightly tracker                            | Informational; does not gate picking.                                                  |
+| `ready-for-agent`         | Ticket is fully specified and agent-grabbable.                       | Nightly tracker, or a human after grooming | Top of the pick order (Step 0).                                                        |
+| `agent:in-progress`       | Nightly agent (or this lane) is investigating/working it right now.  | Lane, at dispatch                          | Skip — already claimed.                                                                |
+| `agent:needs-info`        | Nightly agent needs a reproduction or detail from the reporter.      | Lane, after a failed-repro grooming pass   | Skip until the reporter adds detail.                                                   |
+| `agent:blocked-external`  | Blocked on an upstream or a product decision.                        | Lane or human                              | Skip — not actionable by an agent.                                                     |
+| `agent:already-resolved`  | Nightly agent (or this lane) found this already fixed on main.       | Lane, after proving it with a grep/test    | Terminal — issue gets closed.                                                          |
+| `agent:answered`          | Nightly agent (or this lane) answered a question with evidence.      | Lane, for `question`-type issues           | Terminal if the asker's question is resolved; close.                                   |
+| `agent:fix-proposed`      | Nightly agent opened a PR that fixes this.                           | Nightly tracker                            | Treat like `agent:implemented-in-pr` for picking purposes — skip, a PR already exists. |
+| `agent:implemented-in-pr` | Implemented and gated locally; awaiting PR merge + full CI evidence. | Lane, at Step 3 hand-off                   | Skip — this lane's own terminal state; do not re-dispatch.                             |
+
+Transitions this lane performs itself:
+
+- At dispatch (Step 2): add `agent:in-progress`.
+- At hand-off (Step 3): remove `agent:in-progress`, add `agent:implemented-in-pr`.
+- If grooming proves the issue already fixed: add `agent:already-resolved`, close.
+- If grooming can't establish a repro for a bug/flake: add `agent:needs-info`, comment the
+  findings, move to the next issue.
+
+## Type labels
+
+Type labels describe _what kind_ of issue this is and change how Step 1 grooming proceeds.
+
+| Label                 | Meaning                                                 | How it shapes grooming                                                                                                                                                                 |
+| --------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bug`                 | Something isn't working.                                | Requires an RCA plan before dispatch: evidence-only Phase 1, reproduce before fix. No repro → `agent:needs-info`, not a dispatch.                                                      |
+| `enhancement`         | New feature or request.                                 | Needs acceptance criteria enumerable as greps/tests; write them into the issue body if missing.                                                                                        |
+| `documentation`       | Docs-only change.                                       | Lighter gate: no code test suite required, but still one lane/one PR; likely `no-changeset`.                                                                                           |
+| `question`            | Further information is requested.                       | Answer with evidence in a comment; label `agent:answered`; close if resolved. Not a code dispatch.                                                                                     |
+| `flake`               | Intermittent test or CI failure.                        | Reproduce-before-fix is HARD — same bar as `bug`, no exceptions. A fix without a captured reproduction or an identified mechanism is not dispatchable.                                 |
+| `refactor`            | Internal cleanup, no behavior change.                   | Acceptance criteria are usually "tests still pass, behavior unchanged" — verify there is no user-visible delta before treating it as done.                                             |
+| `ci`                  | CI, build, or release infrastructure.                   | Gates are still typecheck/test/lint/fallow on the touched package, plus verifying the workflow YAML change against a real CI run (cached-green claims don't count for workflow files). |
+| `testing`             | Test coverage or test infrastructure.                   | Acceptance criteria are the new/fixed tests themselves; still needs a real failing-before/passing-after pair.                                                                          |
+| `dx`                  | Developer experience and tooling.                       | Same as `enhancement`; verify the tooling claim against a live run, not just reading the script.                                                                                       |
+| `epic`                | Umbrella issue tracking a set of sub-issues.            | Never dispatch directly — pick a linked sub-issue instead; an epic has no single mergeable PR.                                                                                         |
+| `security`            | Security hardening or vulnerability.                    | Treat like `bug` (RCA required) plus: never weaken an existing security gate to make a test pass.                                                                                      |
+| `needs-investigation` | Needs RCA or a design decision before it is actionable. | Not dispatchable as-is. Grooming produces the RCA or surfaces the design question; the design question itself goes back to the user, it is not the lane's call.                        |
+| `no-changeset`        | PR intentionally ships no release note.                 | Applied to the resulting PR (not the issue) when the fix touches only private/internal code or is docs-only; lets the changeset-coverage CI gate pass without a changeset.             |