Skip to content

Spec-Driven Editing Flow: Can't Easily Update or Refine Existing Specs #1191

Description

@dialedin2014

Summary

Multiple users find it difficult to update, refine, or iterate on existing specs in Spec Kit without creating new branches and redundant specification artifacts. The current workflow for /speckit.specify is optimized for net-new feature creation, but real-world projects often require:

  • Refining specs after feedback or implementation
  • Editing requirements after clarification, planning, or bugfixes
  • Iterating on small changes without repeating all steps or generating a new branch
  • Keeping specs in sync as features evolve (see linked/discussion issues)

Problem

  • /speckit.specify always creates a new branch + artifact, which is great for initial authoring but not for iterative editing or updates.
  • There's no dedicated command (e.g. /speckit.update, /speckit.refine, /speckit.edit, /speckit.bugfix) to refine existing specs within the same branch/artifact.
  • Workarounds (manual file edit, running /speckit.clarify, copying files) are unclear, error-prone, and not universally documented.
  • Many related issues suggest the need for official, user-friendly updating flow, especially for brownfield projects and ongoing refinement.

User examples

What users want

  • A clear, supported workflow to refine specs in place: update requirements, add clarifications, or incorporate bugfixes without new branches.
  • A dedicated update/edit/refine command, or a documented workflow section covering spec and plan evolution.
  • For /speckit.specify (or its successor) to support --update mode or equivalent—detects if on feature branch, loads existing spec file, merges changes, triggers checklist w/o new branch.
  • Option for small, incremental specs (see: tinySpec proposal Proposal: speckit.tinySpec: a lightweight workflow for small tasks #1174).

References (see linked issues)

Proposal

  1. Document best practices for spec evolution: How to update, refine, or deprecate existing specs and plans.
  2. Add a dedicated command for in-place spec updates: /speckit.update, /speckit.refine, or /speckit.edit that modifies the current spec, triggers the checklist, and preserves branching context.
  3. Support an explicit update mode in /speckit.specify: e.g., a flag (--update-current) or detected context that auto-selects and edits the current spec.
  4. Clarify agent and brownfield workflows: Document differences for brownfield projects and non-git use cases, Codex, Cursor, Copilot, etc.
  5. Review and rationalize branching, directory, and naming conventions.
  6. Consider support for incremental and lightweight workflows: Adopt/extend tinySpec (Proposal: speckit.tinySpec: a lightweight workflow for small tasks #1174) for small bugfixes or minor changes.

Impact

Would make Spec Kit safer for iterative, production development; easier to onboard brownfield teams; encourage living spec workflows; reduce confusion/friction from current approach.


Dialedin2014 (user request 2025-11-15)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions