# Spec Driven Spec Edit

> Create or modify individual main spec files under .spec-driven/specs/ directly, without going through the change workflow. For quick corrections, typo fixes, and adding missing spec entries.

- Skill: `kw12121212/spec-driven-spec-edit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kw12121212/spec-driven-spec-edit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kw12121212/spec-driven-spec-edit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: kw12121212 (https://skillmd.com/u/kw12121212)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kw12121212/spec-driven-spec-edit

---


You are helping the user create or modify main spec files under
`.spec-driven/specs/` directly, without going through the change workflow.
This is for lightweight corrections — fixing typos, correcting inaccurate
requirements, or adding missing spec entries.

## This Skill's Commands

If you cannot remember the exact command used by this skill, look it up here
before running anything. Do not guess.

```yaml
verify-spec-mappings: node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings
```

## Prerequisites

The `.spec-driven/` directory must exist at the **project root**. Before
proceeding, verify:
```
ls .spec-driven/
```
If this fails, the project is not initialized. Run `/spec-driven-init` first.

## Steps

1. **Read spec context first** — before making any changes, read:
   - `.spec-driven/config.yaml`
   - `.spec-driven/specs/INDEX.md`
   - any existing main spec files relevant to the user's request

2. **Understand the request** — identify whether the user wants to:
   - add a new spec file or category
   - add new requirements to an existing spec file
   - modify an existing requirement
   - remove one or more existing requirements

3. **Choose the target** — use `INDEX.md` to determine where the content
   belongs:
   - If one or more existing spec files cover the behavior, use those
   - Only create a new spec file if no existing file fits
   - Only create a new category if no existing category fits

4. **Prepare the changes** — draft the exact modifications:
   - For additions: write the new `### Requirement:` heading and body
   - For modifications: show the before and after content
   - For removals: identify the exact `### Requirement:` heading(s) to remove
   - Describe observable behavior only, not implementation details

5. **Present and confirm** — show the user:
   - which file or files will be changed
   - the exact content that will be added, modified, or removed
   - whether `INDEX.md` needs updating

   **Wait for explicit user confirmation before writing anything.**

6. **Apply the changes** — after confirmation:
   - Edit the target spec file(s) under `.spec-driven/specs/`
   - Preserve existing `mapping.implementation` and `mapping.tests`
     frontmatter
   - If the edit changes which implementation or test files evidence the spec,
     update only the mapping frontmatter with repo-relative file paths
   - If a new file or category was created, update `.spec-driven/specs/INDEX.md`
   - For removals, delete the exact `### Requirement:` heading(s) cleanly — do
     not leave orphaned headings or vague remnants

7. **Validate the result** — after editing, verify:
   - Each edited file still follows the standard `### Requirement:` heading
     format
   - Edited files still have valid mapping frontmatter
   - `INDEX.md` correctly reflects all spec files under `.spec-driven/specs/`
   - If format issues are found, fix them immediately
   Run `node {{SKILL_DIR}}/scripts/spec-driven.js verify-spec-mappings` when
   mapping frontmatter changed.

8. **Summarize** — tell the user:
   - which file(s) were changed
   - what was added, modified, or removed
   - whether INDEX.md was updated

## Rules

- Always read existing specs before editing — never edit blind
- Present changes and wait for confirmation before writing
- Prefer existing categories and files unless the content clearly requires a
  new path
- Describe observable behavior only, not implementation details
- Do not implement product code — this skill edits planning artifacts only
- Do not create or interact with `.spec-driven/changes/`
- Keep implementation and test mappings in frontmatter, not in requirement
  prose