/ase-spec-edit

name: ase-spec-edit
argument-hint: "[--help|-h] [--approach|-a] [--grill|-g] [--grill-rounds|-r <n>] [--grill-until|-u MUST|SHOULD|MAY] [--grill-perspective|-p <perspective>] [--grill-ground|-G] [--verify|-v light|none|full] [--worktree|-w <name>[:<branch>]] [--loop|-l] [<query>]"
description: >
    Edit Specification: Use when the user wants to "edit" the
    SpecBook-based specification (SPEC) in one shot from a query, with
    optional grilling, SpecBook validation, looping, and Git worktree
    isolation.
user-invocable: true
disable-model-invocation: false
effort: xhigh

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-spec-edit"> Edit Specification </purpose>

<expand name="getopt" arg1="ase-spec-edit" arg2="--approach|-a --grill|-g --grill-rounds|-r=1 --grill-until|-u=(MUST|SHOULD|MAY) --grill-perspective|-p= --grill-ground|-G --verify|-v=(light|none|full) --worktree|-w= --loop|-l"> $ARGUMENTS </expand>

<objective> *Edit* the specification directly from a query -- creating, revising, or pruning its statements in one shot -- through the states *querying*, *discovering*, *grilling*, *implementing*, and *verifying*. </objective>

@${CLAUDE_SKILL_DIR}/../../meta/ase-format-meta.md @${CLAUDE_SKILL_DIR}/../../meta/ase-format-spec.md @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md @${CLAUDE_SKILL_DIR}/../../meta/ase-common-grill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-common-changeset.md @${CLAUDE_SKILL_DIR}/../../meta/ase-common-approach.md

Procedure ---------

This skill is *plan-less*: it *never* composes or persists a task plan and *MUST* *NOT* call `ase_task_save(...)`. Instead, it applies the requested edit *in place*, so the *implementing* state *requires* `Edit` and `Write` to modify the affected artifacts. Every modification *MUST* stay restricted to the `SPEC` artifacts the edit actually demands -- the kinds `CODE`, `DOCS`, `TASK`, `INFR`, and `OTHR` are *never* touched, except for an entry in an already existing `CHANGELOG.md` file.

<define name="todo-box">

On finishing the state `<arg1/>`, only output the following <template/>, which shows the established <todo-what/> and <todo-how/>, where a still empty <todo-what/> or <todo-how/> renders as `(none)`:

<template> <ase-tpl-head title="EDIT TODO" subtitle="<arg1/>"/>

**WHAT**: <todo-what/>

**HOW**: <todo-how/>

<ase-tpl-foot title="EDIT TODO" subtitle="<arg1/>"/> </template>

</define>

1. **Initialize:**

1. Set <query><getopt-arguments/></query> (with any leading and trailing whitespace stripped), set <todo-what></todo-what> and <todo-how></todo-how> (both empty), and set <worktree-dir></worktree-dir> (empty). Do not output anything.

2. If <getopt-option-grill-rounds/> is not a positive integer, only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ ERROR: invalid `--grill-rounds` value: **<getopt-option-grill-rounds/>** </template>

3. Resolve a potentially misparsed former boolean `--worktree` option:

<expand name="changeset-ambiguity" arg1="✪ skill: **ase-spec-edit**"></expand>

2. **Iterate:**

Perform the states (1) *querying*, (2) *discovering*, (3) *grilling*, (4) *implementing*, and (5) *verifying* below as one *iteration*. Without `--loop` perform exactly *one* iteration. Under `--loop` *repeat* the iteration until the *querying* state receives a `STOP SKILL` result. Do not output anything in this item.

3. **State: querying:**

1. <if condition="<query/> is empty">

1. In the following, you *MUST* *NOT* use your built-in <user-dialog-tool/> tool! Instead, you *MUST* just show a custom dialog according to the expanded `custom-dialog` definition. You *MUST* closely follow this definition. Its only answer option is the fixed `STOP SKILL`, so the user normally answers with the edit query in *one* free-text reply:

<expand name="custom-dialog" arg1="--other"> Edit Query: What is your edit query? STOP SKILL: stop the entire skill immediately </expand>

2. If <result/> is `STOP SKILL` or `CANCEL`, only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ✪ skill: **ase-spec-edit**, ▶ status: **editing finished** </template>

Otherwise, strip any leading `OTHER: ` prefix from <result/> and set <query/> to the remainder.

</if>

2. Convert the <query/> *fresh* into <todo-what/> -- the domain-specific, non-implementation-detail information -- and <todo-how/> -- the remaining information -- discarding all <todo-what/>/<todo-how/> content of any previous iteration. Without `--grill` you *MUST* *NOT* ask any clarifying questions and during later implementation just interpret the query best-effort. Do not output anything.

3. Expand the following:

<expand name="todo-box" arg1="current state (after querying)"></expand>

4. Set <query></query> (clear the query, so every further `--loop` iteration asks for a fresh one). Do not output anything.

4. **State: discovering:**

1. <if condition="<getopt-option-worktree/> is not empty and <worktree-dir/> is empty">

One *single* worktree serves the whole skill run: it is prepared *once* before the first discovery, so discovering, grilling, and implementing all operate on the *same* tree, and all further `--loop` iterations land in it, too.

<expand name="c