Skip to content

[Change] Improve backlog refine and CLI startup #166

@djm81

Description

@djm81

Why

Four improvements are needed:

  1. Startup delay: On machines with security scanning (e.g. xagt), the CLI takes 5–10s before first output. Users need faster feedback (e.g. version line before checks).

  2. Backlog refine --limit loop: With --limit N, if the first N items are already refined, the user gets N skips every run. We need --ignore-refined (default) so limit applies to items that need refinement.

  3. Focused refinement: There is no way to refine a single story by ID. Users need --id ISSUE_ID for focused refinement.

  4. Copilot interactive refinement: The backlog-refine prompt should instruct the AI to show each story, explain ambiguities, ask for clarification, re-refine until the user approves, then update—for an interactive, stakeholder-friendly experience.

What Changes

  • MODIFY cli.py – Ensure first output (version line) before startup checks; optional PyPI timeout.
  • MODIFY backlog_commands.py – Add --ignore-refined/--no-ignore-refined, --id; filter logic so limit applies to items needing refinement when ignore-refined.
  • MODIFY startup_checks.py – Optional timeout for version check.
  • MODIFY specfact.backlog-refine.md – Add interactive refinement (Copilot) section.
  • MODIFY backlog-refinement spec – Add scenarios for ignore-refined and --id.
  • NEW Tests for ignore-refined and --id behavior.
  • MODIFY Docs/AGENTS.md – Document --skip-checks for startup.

Acceptance Criteria

  • First CLI output appears before slow startup checks; or --skip-checks documented for fast startup.
  • specfact backlog refine --limit N (default --ignore-refined) returns up to N items that need refinement.
  • specfact backlog refine --no-ignore-refined --limit N preserves current behavior.
  • specfact backlog refine --id 123 refines only item 123; clear error if not found.
  • Prompt includes interactive refinement instructions (present story → ambiguities → ask clarification → re-refine until approved → then update).
  • OpenSpec spec updated; tests added for new options.

OpenSpec Change Proposal: improve-backlog-refine-and-cli-startup

Metadata

Metadata

Assignees

Labels

Projects

Status

Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions