/ase-spec-edit

name: ase-spec-edit
argument-hint: "[--help|-h] [--grill|-g] [--grill-rounds|-r <n>] [--verify|-v] [--branch|-b <name>] [--worktree|-w] [--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="--grill|-g --grill-rounds|-r=1 --verify|-v --branch|-b=current --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

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.

<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>

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. Resolve the `SPEC` artifacts by calling the `ase_artifact_list(kind: [ "spec" ])` tool of the `ase` MCP server *once* and reading the returned `artifacts` array of `{ kind, files }` objects to obtain the project-relative file list. Do not output anything.

2. Read the **SpecBook SCHEMA Model** of the project (resolved as described in `ase-format-spec.md`) to learn the allowed object kinds, properties, nestings, and value constraints. Do not output anything.

3. Read all resolved `SPEC` artifacts which are related to <todo-what/> and <todo-how/>, and check the structure of the existing specification -- its artifacts, object kinds, ids, properties, descriptions, and `[[xxx]]` references -- to understand the overall models and their relationships. Do not output anything.

5. **State: grilling:**

Enter this state only if <g