capture-followup

Files (2)

• SKILL.md
• followup-contract.test.py

SKILL.md (first lines)

# Follow-up Capture (Deferred Work → Backlog)

Shared files: a path written `@rules/…`, `@skills/…`, `@templates/…` or `@docs/…` is relative to the
plugin root, `${CLAUDE_PLUGIN_ROOT}` — not to the project being worked on. Read it from there.

**Usage:** `/architect:capture-followup [title] [--parent=<local_id|#iid>] [--from=<file|issue-ref>] [--queue-only] [--flush] [--dry-run] [--auto] [--lang=en|ja]`

With a title/--from, appends to the queue (and offers a flush); --queue-only stops after the append
(the form the feeder skills use mid-run); --flush (or no args with a non-empty queue) reviews the
queue and creates the Issues after an approval gate.

## Desired Outcome

Work discovered mid-delivery that cannot be done now stops disappearing into comments and review
prose. Instead it flows through three states, each durable:

- **Queued.** A `reports/backlog/followup-queue.md` entry records the task, its proposed parent,
  and where it was discovered — appendable at any point during `/architect:implement-backlog`,
  `/architect:review-issue`, or `/architect:merge-issue` without a remote write or an approval
  interruption.
- **Created.** After an explicit approval gate, each queued entry becomes a tracker Issue
  (`glab` / `gh`) labeled `status::todo`, linked to its parent Sub-Epic (or, explicitly, Epic),
  and appended to `reports/backlog/backlog-manifest.json` as a node the rest of the backlog
  family understands.
- **Delivered.** The new Issues are ordinary backlog Issues: `/architect:deliver-backlog` picks
  them up as `status::todo` with no special handling.

Runs against the **target project** (the one holding `reports/backlog/backlog-manifest.json` and
the tracked repository). It never edits nexus-architect itself.

## Decision Criteria

- **Parent selection precedence** — (1) `--parent=<local_id|#iid>` always wins. (2) Otherwise
  default to the parent Sub-Epic of the Issue currently in flight: the single `status::doing`
  Issue, resolved from the manifest's `impl.status` — when the tracker label and `impl.status`
  disagree, the tracker wins (same rule as `/architect:deliver-backlog`). (3) When zero or
  multiple Issues are `doing`, ask via AskUserQuestion. **Epic-direct attachment is allowed only
  explicitly** (`--parent=E<n>` or chosen in the dialog) — a cross-cutting follow-up may
  legitimately have no Sub-Epic home, but the default never silently picks the Epic.
- **Queue vs create** — Feeder skills always append with `--queue-only`; remote creation happens
  only past the Step 3 gate. Never create an Issue the user has not approved (unless `--auto`).
- **Fabrication ban** — The Issue body derives from the recorded finding (the queue entry, the
  `--from` source, or the user's words). Do not invent acceptance criteria, endpoints, or
  numbers; a follow-up whose "done" condition is unknown gets a single criterion restating the
  finding to resolve, marked `TBD`.
- **Follow-ups are not an escape hatch** — A `[B]` blocker, a failing preflight check, or an
  unmet criterion needed for the *current* Issue's merge is handled by the owning skill's own
  loop; only genuinely deferrable work belongs here.

## Prerequisites

| File / source | Required/Recommended | Produced by |
|---------------|----------------------|-------------|
| `reports/backlog/backlog-manifest.json` | Required | /architect:export-backlog |
| `glab` / `gh` authenticated for the target project | Required (flush only) | user |
| `reports/backlog/followup-queue.md` | Optional (created on first capture) | this skill + feeder skills |

Read the output language from `work/pipeline-progress.json` (`options.output_language`, default
`en`); `--lang` overrides. Queue entries, Issue titles/bodies, and reports use that language;
label keys, local IDs, and traceability IDs stay in English.

## Follow-up ID & Manifest Contract

Follow-up Issues live in their **own local-ID namespace** so they can never collide with the
positional IDs `/architect:export-backlog` synthesizes from reports:

- **Format**: `<parent_local_id>.F<n>` — e.g. `SE1.2` → `I1.2.F1`, `I1.2.F2`; an Epic-direct
  follow-up under `E1` is `I1.F1`. The `I` prefix marks the level (always `issue`); the `F<n>`
  suffix marks the namespace.
- **Allocation at create time** (Step 4, not at queueing): `n` = max existing `F` index among the
  parent's children in the manifest, plus 1. Queued-but-not-created entries reserve nothing, so
  dropping one leaves no gap.
- **Collision rule** — `export-backlog --update` re-synthesizes only positional IDs
  (`I1.2.1 … I1.2.n`); it must never assign, renumber, or reassign a `*.F<n>` node or any node
  carrying `origin` (stated on its side too). The two namespaces are disjoint by construction.

The manifest node uses the exact shape `export-backlog` defines, plus one new field, `origin`:

```json
{
  "local_id": "I1.2.F1",
  "level": "issue",
  "title": "Extract retry policy into shared config",
  "body": "## How\n…\n## Acceptance Criteria\n- [ ] …\n## References\n…",
  "labels": ["type:issue", "status::todo", "followup", "domain:payments"],
  "parent_local_id": "SE1.2",
  "source_reports": ["reports/backlog/impl-log/I1.2.3.md"],
  "traceability": ["NFR-03"],
  "origin": {
    "discovered_in": "I1.2.3",
    "source": "implement",
    "reference": "reports/backlog/impl-log/I1.2.3.md#finding-2",
    "queued_at": "2026-08-06T02:00:00Z"
  },
  "remote": { "id": 401, "iid": 57, "url": "…", "created_at": "…" }
}
```

- `origin.source` ∈ `implement | review | merge | manual`; `origin.discovered_in` is the local ID
  (or `#<iid>`) of the item being worked when the task surfaced; `origin.reference` points at the
  recorded finding (impl-log anchor, review doc, comment URL).
- `labels` is the **creation seed, not live state** (the standing manifest rule): seeded with
  `type:issue` (GitLab fallback: `type::issue`), `status::todo`, `followup`, and the `domain:` /
  `tier:` labels inherited from the parent Sub-Epic. Status advances on the tracker and in
  `impl.status`, never here.
- The node is appended to the manifest **immediately after each successful create**, with
  `remote` filled in, so an interrupted flush resumes cleanly.

This contract is asserted as behaviour by `skills/capture-followup/followup-contract.test.py`
(F-index allocation, namespace disjointness, node shape, parent resolution) — run it after
changing this section.

## Queue File Contract

`reports/backlog/followup-queue.md` — markdown (not JSON) so the user can hand-edit entries
before a flush. Created on first capture with the required YAML frontmatter (`title`,
`schema_version: 1`, `phase`, `skill: capture-followup`, `generated_at`, `input_files`). One
section per entry:

From wfukatsu/nexus-architect, MIT.

More from wfukatsu/nexus-architect