talont-org/enrich-issues

enrich-issues Skill

Backfill ## Requirements sections on existing GitHub issues labelled recipe:implementation. Complements prepare-issue (which enriches at creation time) by handling the pre-existing backlog.

Interface

/autoskillit:enrich-issues [--issue N] [--batch N] [--dry-run] [--repo owner/repo]

• --issue N — enrich a single issue by number
• --batch N — filter by batch:N label in addition to recipe:implementation
• --dry-run — preview generated requirements without editing issues
• --repo owner/repo — override the default repository

Workflow

Step 0: Parse Arguments

Parse ARGUMENTS for:

• --issue N → set issue_number = N
• --batch N → set batch = N
• --dry-run → set dry_run = true
• --repo owner/repo → set repo = "owner/repo"

Step 1: Authenticate

gh auth status

Fail fast with a clear error if authentication is not available. Do not proceed past this step if auth fails.

Step 2: Resolve Repo

If --repo owner/repo was provided, use it. Otherwise use gh's default repo context:

gh repo view --json nameWithOwner -q .nameWithOwner

Step 3: Fetch Candidates

Single issue (--issue N):

gh issue view N --json number,title,body,labels

Wrap as a single-element list.

Batch (--batch N):

gh issue list \
    --label "recipe:implementation" \
    --label "batch:N" \
    --json number,title,body,labels \
    --limit 100

Default (no flags):

gh issue list \
    --label "recipe:implementation" \
    --json number,title,body,labels \
    --limit 100

Step 4: Idempotency Filter

For each candidate issue, check whether its body already contains ## Requirements.

• If the body already contains ## Requirements: skip it, add its number to skipped_already_enriched. Log: "Issue #N already enriched — skipping."
• If the body does not contain ## Requirements: add to candidates list.

If no candidates remain after filtering, emit the result block immediately and exit.

Step 5: Per-Issue Analysis

Process up to 8 candidates in parallel using subagents (model: "sonnet"). For each candidate:

5a. Fetch Full Content

gh issue view N --comments --json body,comments,title,labels

5b. Codebase Cross-Reference

Search the codebase for files, modules, and system names mentioned in the issue title and body. Verify claims against actual code before incorporating them into requirements. Do not invent codebase details.

5c. Assess Enrichability

Classify the issue into one of three categories:

Too vague — cannot extract clear acceptance criteria (e.g., "improve X", no measurable outcome, contradictory claims):

• Append a ## Triage Note section to the issue body:

  ENRICH_BODY_FILE="{{AUTOSKILLIT_TEMP}}/enrich-issues/enrich_{N}_$(date +%s).md"
  mkdir -p "$(dirname "$ENRICH_BODY_FILE")"
  gh issue view N --json body --jq '.body' > "$ENRICH_BODY_FILE"
  printf '\n\n---\n\n## Triage Note\n\nThis issue needs more detail before requirements can be generated. Consider: What is the expected outcome? What signals success? If the goal is unclear, relabeling to `recipe:remediation` may be appropriate for investigation first.\n' \
    >> "$ENRICH_BODY_FILE"
  gh issue edit N --body-file "$ENRICH_BODY_FILE"
  sleep 1
  

• Add to skipped_too_vague.

Mixed concerns — the issue describes two or more independently-completable sub-features or mixes a bug fix with a new feature:

• Append a ## Triage Note section to the issue body:

  ENRICH_BODY_FILE="{{AUTOSKILLIT_TEMP}}/enrich-issues/enrich_{N}_$(date +%s).md"
  mkdir -p "$(dirname "$ENRICH_BODY_FILE")"
  gh issue view N --json body --jq '.body' > "$ENRICH_BODY_FILE"
  printf '\n\n---\n\n## Triage Note\n\nThis issue mixes independent concerns. Consider running `/autoskillit:issue-splitter` to split it into focused sub-issues before enrichment.\n' \
    >> "$ENRICH_BODY_FILE"
  gh issue edit N --body-file "$ENRICH_BODY_FILE"
  sleep 1
  

• Add to skipped_mixed_concerns.

Well-defined — a single, coherent goal with extractable acceptance criteria:

• Proceed to requirement generation (Step 5d).

5d. Generate Requirements

Requirements are acceptance criteria, not implementation steps.

Rules:

• State observable, testable outcomes: "The system must X" not "Do X"
• Group by co-implementation concern. Name each group with a short uppercase abbreviation (2–5 letters, e.g., AUTH, API, DATA, CLI, UI)
• Format: **REQ-{GRP}-NNN:** {single-sentence condition}.
  • NNN is zero-padded and resets per group (001, 002, ...)
• Include a brief per-group background paragraph before the requirement list
• Verify all codebase references against actual code found in Step 5b

Example output structure:

## Requirements

### API Layer

The API layer exposes skill execution to MCP clients through the headless executor.

- **REQ-API-001:** The `enrich_issues` tool must accept `issue_number`, `batch`,
  `dry_run`, and `repo` parameters.
- **REQ-API-002:** The tool must be gated behind `open_kitchen`.

### Data Model

...

5e. Apply or Preview

• If --dry-run: print the generated ## Requirements section to stdout. Do not call gh issue edit. Set dry_run: true in the result.

• Otherwise: append the section to the original issue body:

  ts=$(date +%Y-%m-%d_%H%M%S)
  EDIT_BODY_FILE="{{AUTOSKILLIT_TEMP}}/enrich-issues/edit_body_${ts}.md"
  REQUIREMENTS_FILE="${EDIT_BODY_FILE%.md}_req.md"
  mkdir -p "{{AUTOSKILLIT_TEMP}}/enrich-issues"
  
  # Fetch current body immediately before editing (avoids shell interpolation):
  gh issue view N --json body -q .body > "${EDIT_BODY_FILE}"
  
  # Populate ${REQUIREMENTS_FILE} with generated requirements, then:
  printf '\n\n## Requirements\n\n' >> "${EDIT_BODY_FILE}"
  cat "${REQUIREMENTS_FILE}" >> "${EDIT_BODY_FILE}"
  
  gh issue edit N --body-file "${EDIT_BODY_FILE}"
  sleep 1  # Rate-limit discipline: throttle within each subagent
  

  Always fetch the current body immediately before editing to avoid overwriting concurrent changes.

Step 6: Emit Result Block

After processing all candidates, emit to stdout:

---enrich-issues-result---
{
  "enriched": [{"issue_number": N, "requirements_count": M, "groups": ["GRP1", "GRP2"]}],
  "skipped_already_enriched": [N, ...],
  "skipped_too_vague": [N, ...],
  "skipped_mixed_concerns": [N, ...],
  "dry_run": true|false
}
---/enrich-issues-result---

Critical Constraints

NEVER:

• Edit an issue body without first fetching its current content immediately before the edit
• Force requirements when the issue is too vague — comment and move on
• Apply ## Requirements to an issue that already has one (idempotency)
• Skip the result block — always emit it, even on dry-run or when all issues were skipped
• Use --body shell substitution (--body "$(...)) for gh issue edit — always write to {{AUTOSKILLIT_TEMP}}/enrich-issues/edit_body_{timestamp}.md and use --body-file
• Run subagents in the background (run_in_background: true is prohibited)

ALWAYS:

• Respect --dry-run: never call gh issue edit when this flag is set
• Verify codebase claims before incorporating them into requirements
• Use model: "sonnet" for per-issue analysis subagents
• Emit the ---enrich-issues-result--- block as the final output