Create Backlog Item

Create Backlog Item

Capture a new backlog item and append it to .claude/BACKLOG.md in the correct priority section.

Arguments

$0 selects the operating mode:

/create-backlog-item                                   # guided intake
/create-backlog-item quick GitHub milestone skill      # quick entry
/create-backlog-item --auto vercel skills npm package  # autonomous (agent use)

Workflow

Step 1: Collect Item Fields

If $0 is --auto:

Title = $1 onward (all remaining words joined). Do not call AskUserQuestion. Instead:

1. Search research/ recursively for any file whose name or content matches the title (case-insensitive). Read the best match.
2. Search .claude/BACKLOG.md for related items to understand existing priority patterns.
3. Derive all fields from the research file, task description, and available context:
   • Title: from $1 onward
   • Priority: infer from description urgency keywords (critical, required, must → P1; nice to have, optional → P2; default P1)
   • Description: summarize from research file overview + problem statement
   • Source: "Agent task — auto-derived from research/{filename}"
   • Type: infer from description (install, integrate, add → Feature; default Feature)
4. Log every decision:

[AUTO] Title: {title} — from $1 onward
[AUTO] Priority: P1 — inferred from description (no urgency keywords found, defaulting P1)
[AUTO] Description: derived from research/skill-generation-tools/vercel-labs-skills.md
[AUTO] Source: Agent task — auto-derived from research/skill-generation-tools/vercel-labs-skills.md
[AUTO] Type: Feature — inferred from "integrate" keyword

Proceed to Step 2 (validate). Skip Step 7 (GitHub issue) — auto mode does not create GitHub issues unless --create-issue is also passed.

If $0 is empty (guided intake):

Use AskUserQuestion with two questions:

Question 1: "What is the title of this backlog item?"
  header: "Title"
  options: (free text — no options; user will type)

Question 2: "What priority?"
  header: "Priority"
  options:
    - label: "P0 — Must have"
    - label: "P1 — Should have"
    - label: "P2 — Nice to have"
    - label: "Idea — Not yet sized"

Then ask:

Question 3: "Describe the item. Include: what the problem is, what success looks like, and any known constraints or research questions."
  header: "Description"

Then ask:

Question 4: "What is the source or trigger for this item? (e.g., code review, user request, session observation — or press Enter to skip)"
  header: "Source"
  options:
    - label: "Code review"
    - label: "User request"
    - label: "Session observation"
    - label: "Research finding"
    - label: "Skip"

Then ask:

Question 5: "What type of work is this?"
  header: "Type"
  options:
    - label: "Feature"
    - label: "Bug"
    - label: "Refactor"
    - label: "Docs"
    - label: "Chore"

If $0 is quick:

Title = $1 onward. Ask only:

• Priority (Question 2 above)
• Description (Question 3 above)

Source defaults to "Session observation". Type defaults to "Feature".

Step 2: Validate Inputs

Required fields: title, priority, description.

• If any required field is missing or empty: report which field is missing and stop.
• title must be non-empty after trimming whitespace.
• description must be non-empty after trimming whitespace.

Step 3: Duplicate Detection

Read .claude/BACKLOG.md. Search all H3 headings for case-insensitive overlap with title.

If a match is found within edit distance ≤ 2 tokens (same first 3 words), report:

Possible duplicate: "{existing title}" already exists in {section}.
Proceed anyway? (y/n)

Use AskUserQuestion with Yes / No options. If No: stop.

In --auto mode: if a duplicate is found, log [AUTO] STOP — duplicate detected: "{existing title}" in {section} and stop without writing. Do not ask.

Step 4: Compose Item Block

Format today's date as YYYY-MM-DD (use system date).

### {title}

**Source**: {source, or "Not specified" if skipped}
**Added**: {YYYY-MM-DD}
**Priority**: {P0|P1|P2|Idea}
**Type**: {type}
**Description**: {description}

If research questions were embedded in the description (lines starting with ? or Research:), extract them into a separate **Research first**: field:

**Research first**: {extracted questions}

Step 5: Write to BACKLOG.md via backlog script

Build the command. Base:

uv run .claude/skills/backlog/scripts/backlog.py add \
  --title "{title}" \
  --priority "{priority}" \
  --description "{description}" \
  --source "{source}" \
  --type "{type}" \
  -R Jamie-BitFlight/claude_skills

• If research_first is non-empty: append --research-first "{research_first}"

GitHub Issue creation:

• If priority is P0 or P1 and (guided/quick mode with user said Yes, or --auto with --create-issue passed): do NOT add --no-create-issue (script creates issue by default).
• If priority is P2 or Idea: add --no-create-issue.
• If priority is P0 or P1 and user said No (skip): add --no-create-issue.
• If $0 is --auto and user did not pass --create-issue: add --no-create-issue.

Step 6: Confirm Write

The script outputs the confirmation. Report to user:

Backlog item created.

  Title:    {title}
  Priority: {priority}
  Section:  {section heading}
  Added:    {date}

Next steps:
  Groom:  /groom-backlog-item {title}
  Work:   /work-backlog-item {title}

Error Handling

• Missing required field: report field name, stop.
• Duplicate detected and user says No: stop without writing.
• backlog script fails: report error, stop.
• GITHUB_TOKEN not set (for P0/P1 issue creation): script reports; item still written to BACKLOG.md.

Completion Criteria

• backlog add invoked successfully
• Item written to correct BACKLOG.md section (script handles)
• Frontmatter counts updated (script handles)
• GitHub Issue created and **Issue**: #N written back (P0/P1 only, if --create-issue; script handles)
• Next-step commands shown to user