spec-driven-spec-content

Prerequisites

.spec-driven/

ls .spec-driven/

/spec-driven-init

Steps

1. Select the change — run

   node {{SKILL_DIR}}/scripts/spec-driven.js modify

   to list active changes. Ask which change to edit if the user did not specify one.
2. Understand the request — identify whether the user wants to:
   • add new spec content
   • extend an existing spec
   • modify an existing requirement
   • remove one or more existing requirements
3. Read index-first context — before deciding any path, read:

   • .spec-driven/config.yaml

   • .spec-driven/specs/INDEX.md

   • any existing files under

     .spec-driven/changes/<name>/specs/

     that already look related
4. Choose candidate targets from

   INDEX.md

   — use the index to determine which existing categories and spec files might already cover the requested behavior.
   • If one or more candidates exist, read the full main spec files before making any routing decision
   • Only create a new category if no existing category fits the behavior
   • Only create a new spec file inside an existing category if the behavior does not fit any existing file in that category
5. Decide the delta spec path — classify the request into exactly one of:
   • update an existing delta file that mirrors an existing main spec file
   • create a new delta file under an existing category
   • create a new delta file under a new category
   • revise existing requirements in a delta file that already exists
   Keep the delta path aligned with the main spec path that should exist after archive.
   • If the chosen delta spec file already exists under

     .spec-driven/changes/<name>/specs/

     , read that exact file before appending or revising content
6. Edit the delta spec content — preserve the standard delta format:
   • Use

     ## ADDED Requirements

     for new requirements
   • Use

     ## MODIFIED Requirements

     for changed requirements, including a

     Previously:

     note
   • Use

     ## REMOVED Requirements

     for deletions, including the reason
   • Keep

     ### Requirement:

     headings intact
   • Describe observable behavior, not implementation details
7. Handle removals explicitly — if the request removes spec content:
   • identify the exact

     ### Requirement:

     heading or headings being removed
   • write those removals explicitly in the delta file
   • do not use vague phrasing like "remove old spec" or "delete obsolete content"
   • if the target requirement is ambiguous after reading the relevant specs, stop and ask the user which requirement should be removed
8. Run the final spec format check — after any spec edit, run:

   node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>

   • Treat missing artifacts, malformed delta section markers/headings, and other spec structure problems as the format issues to repair
   • Fix any safe format issues immediately and rerun

     verify

   • If

     verify

     reports only non-format workflow blockers such as open questions in

     questions.md

     , surface those separately instead of misreporting them as spec-format failures
   • Do not finish without this check
   • If unresolved format or structure errors remain, report them clearly to the user
9. Summarize the routing decision — tell the user:
   • which category/file was chosen
   • whether it was an existing file, new file, or new category
   • whether the change added, modified, or removed requirements
   • whether the final format check passed

Rules

• Read

  .spec-driven/specs/INDEX.md

  before choosing a category or file name
• Prefer existing categories and files unless the content clearly requires a new path
• Read the relevant main specs before editing delta specs
• If the chosen delta file already exists, read that exact file before editing it
• Do not implement code — this skill edits planning artifacts only
• Always finish with a spec format check