Why
Four improvements are needed:
-
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).
-
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.
-
Focused refinement: There is no way to refine a single story by ID. Users need --id ISSUE_ID for focused refinement.
-
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
OpenSpec Change Proposal: improve-backlog-refine-and-cli-startup
Why
Four improvements are needed:
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).
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.Focused refinement: There is no way to refine a single story by ID. Users need
--id ISSUE_IDfor focused refinement.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
cli.py– Ensure first output (version line) before startup checks; optional PyPI timeout.backlog_commands.py– Add--ignore-refined/--no-ignore-refined,--id; filter logic so limit applies to items needing refinement when ignore-refined.startup_checks.py– Optional timeout for version check.specfact.backlog-refine.md– Add interactive refinement (Copilot) section.--skip-checksfor startup.Acceptance Criteria
--skip-checksdocumented 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 Npreserves current behavior.specfact backlog refine --id 123refines only item 123; clear error if not found.OpenSpec Change Proposal: improve-backlog-refine-and-cli-startup