## NAME
`ase-spec-edit` - Edit Specification
## SYNOPSIS
`ase-spec-edit`
[`--help`|`-h`]
[`--approach`|`-A`]
[`--grill`|`-g`]
[`--grill-auto`|`-a`]
[`--grill-rounds`|`-r` *n*]
[`--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`]
[`--grill-perspective`|`-p` *perspective*]
[`--ground`|`-G`]
[`--verify`|`-v` `light`|`none`|`full`]
[`--worktree`|`-w` *name*[`:`*branch*]]
[`--loop`|`-l`]
[*query*]
## DESCRIPTION
The `ase-spec-edit` skill edits the *SpecBook*-based specification
(`SPEC`) *directly* from a *query*, in one shot and without any task
plan ceremony. It is the specification-level counterpart of
`ase-code-edit` and a *plan-less* alternative to `ase-sync-import` and
`ase-sync-reconcile` whenever the specification has to be changed from a
plain description instead of from a foreign source or another artifact
kind.
Each single-shot run (or each `--loop` iteration) walks through five
states: *querying* (take the *query* argument or ask for a query via an
interactive `Edit Query` dialog, and split it into its domain-specific
WHAT and its implementation-detail HOW parts), *discovering* (resolve
the `SPEC` artifacts, read the *SpecBook* schema configuration of the
project, and read the specification artifacts related to the query),
*grilling* (optionally decide the approach in an approach round and
stress-test the query with rounds of questions), *implementing* (apply
the change set in place, honoring the GENERIC and SPECIFYING tenets and
the `SPEC` format contract), and *verifying* (validate the specification until it
passes, unless disabled via `--verify none`). The *querying* state, the approach round, and
every *grilling* round close with an `EDIT TODO` box showing the established
`WHAT` and `HOW` information.
Once at its end (after all `--loop` iterations), the skill reports its
*own decisions* -- those neither made in the query nor during grilling,
including the answers auto-chosen by `--grill-auto` -- as a `WHAT`/`WHY`
table for review. It covers only decisions of the focus areas `DOM`
(domain), `IFC` (interface), and `ARC` (architecture), ranked in this
order and numbered `D01`, `D02`, etc., and is skipped without any own
decision.
The change set stays strictly restricted to the `SPEC` artifacts -- the
artifact kinds `CODE`, `DOCS`, `TASK`, `INFR`, and `OTHR` are never
touched, except for an entry in an already existing `CHANGELOG.md`
file. Every generated artifact carries the current `Created:` and
`Modified:` timestamps, and every changed artifact gets its `Modified:`
timestamp refreshed.
## OPTIONS
- `--approach`|`-A`:
Decide the overall specification approach in a special *approach
round* of grilling, which works like a regular `--grill` round, but
raises only 1-4 questions on the overall approach, with the
competing approaches as answer alternatives (their pros and cons
show up in the hover card), and is never finished early by
`--grill-until`. Alone, it is announced as `GRILLING (approach)`;
together with `--grill`, it is the round 0 before the regular
rounds, announced as `GRILLING ROUND 0/L (approach)`, followed by
`GRILLING ROUND 1/L` etc. Its answers are chosen automatically
under `--grill-auto`, the `black` project boxing, or in headless
mode, and `SKIP GRILLING` skips it together with all regular
rounds. The decided approach is merged into the HOW part of the
query. Without `--approach`, no approaches are determined at all.
- `--grill`|`-g`:
Grill the query before implementing, similar to `ase-task-grill`:
raise 1-10 questions per round which resolve the open points of the
query. Each question carries a `FOCUS-AREA` -- `DOMAIN`
(domain-specifics, must be clarified), `INTERFACE` (externally
observable behavior or UI/API interfaces, must be clarified),
`ARCHITECTURE` (structure, wiring, placement, or dependencies,
should be clarified), `IMPLEMENTATION` (inner technical details,
can be clarified), `REGRESSION` (what must not break, should be
clarified), or `CONFIRMATION` (what proves the specified behavior,
should be clarified) -- and a 1-3 word `TOPIC` hint. The questions
of a round are sorted by descending focus area importance
(`DOMAIN`, `INTERFACE`, `ARCHITECTURE`, `IMPLEMENTATION`,
`REGRESSION`, `CONFIRMATION`). Questions of focus area
`REGRESSION` are raised only under `--verify light` or `full`, and
those of focus area `CONFIRMATION` only under `--verify full`, as
only then a verification honors their decisions.
All questions of a round are announced together below a `GRILLING ROUND K/L` line (the round numbering is
omitted when only a single round is performed) as a
`QUESTION`/`ANSWERS` table with one row per question, each row
carrying two to three grounded answer alternatives (with the
alternative reflecting the current understanding marked with `⚑`,
and the one critically judged best, if any, marked with `★` as the
recommendation, whose rationale shows up in the hover card of every
answer). They are then asked in *one* batch via a single interactive dialog,
whose question asks for the combined answer to all (or a subset) of
the listed questions and whose only answer options are the fixed
`AUTO GRILLING` (answer this and all remaining rounds of the current
iteration like `--grill-auto`), `SKIP GRILLING` (skip the remaining
grilling), and `STOP SKILL` (stop the skill) ones, plus free-text
input. The questions are numbered
`1`, `2`, etc. and their answer alternatives are lettered `A`, `B`,
etc., so the free-text input can cherry-pick answers with short
responses matching `\d+[a-zA-Z]` (like `1A 2c`), freely mixed with
keyword text. The answers are merged back into the WHAT and HOW
parts of the query. Without `--grill`, no questions are asked at
all.
- `--grill-auto`|`-a`:
Grill the query like `--grill` (which it implies), but answer the
questions automatically instead of asking the user via the
interactive dialog: every question gets its `★` recommended answer,
while a question without a recommendation stays unanswered, like a
question skipped in an interactive reply. The questions table is
still shown, followed by a status line naming the auto-chosen
answers, like `auto-chosen answers 1A 3B`.
- `--grill-rounds`|`-r` *n*:
The *maximum* number of grill rounds to apply (default: `1`). Each
round starts from scratch from only the current WHAT and HOW parts,
forgetting all information of previous rounds, and closes with an
`EDIT TODO` box. The grilling stops early -- announced by a
`grilling finished early` status line -- once a round, even the
first one, finds the open points clear enough according to
`--grill-until`. Only effective together with `--grill` or `--grill-auto`.
- `--grill-until`|`-u` `MUST`|`SHOULD`|`MAY`:
Grill until at least all open points of the given severity or
higher are clear (default: `MUST`), where the severity follows from
the focus area: `MUST` (`DOMAIN`, `INTERFACE`), `SHOULD`
(`ARCHITECTURE`, `REGRESSION`, `CONFIRMATION`), and `MAY`
(`IMPLEMENTATION`). Independent of this, every open point is rated
with an individual impact (`HIGH`, `MEDIUM`, or `LOW`), which
decides which points are raised as questions and in which order
within a focus area. Only effective together with `--grill` or `--grill-auto`.
- `--grill-perspective`|`-p` *perspective*:
Grill exclusively from the logical *perspective* -- a keyword or
short hint like `domain`, `performance`, or `security`. The
perspective acts as an exclusive lens: only open points relevant from
this perspective are raised as questions, while every question still
carries its focus area, severity, and impact. The active perspective
is shown in the announcement line, like `GRILLING (security)`.
Without a perspective, the grilling is holistic. Only effective together with `--grill`,
`--grill-auto`, or `--approach`.
- `--ground`|`-G`:
Ground the edit in facts instead of the world knowledge of the
model alone: once after discovering, each dimension -- `WHAT` (the
requirements), `HOW` (the realization), and `WHEN` (the
verification, skipped under `--verify none`) -- is grounded in
parallel. Its artifacts (`SPEC` and `DOCS` for `WHAT`, `CODE` and
`INFR` for `HOW`, and the test and CI files for `WHEN`) are scanned
for the project facts relevant to the query, and the Internet/Web is
searched iteratively, with at most 5 searches per dimension, for the
established practices, standards, patterns, and pitfalls about it.
Both focus especially on the special and less known terms and
concepts and on the aspects which potentially could be outdated in
the model knowledge, judging every Web fact by its date or version.
These facts serve all subsequent states: under `--grill` all rounds,
both for raising the questions and for preferably deriving their
answer alternatives (shown in the announcement line, like
`GRILLING (security, grounded)`), as well as the implementing and
verifying. If no usable facts are found, a warning is shown and the
edit falls back to model knowledge.
- `--verify`|`-v` `light`|`none`|`full`:
Verify the edited specification by validating it via *SpecBook*
linting and fixing the reported diagnostics in the affected `SPEC`
artifacts, for at most ten rounds. Any diagnostics remaining after
the last round are listed as `REMAINING DIAGNOSTICS`. The default
`light` and the level `full` perform the same validation. The level
`none` strictly performs no validation at all.
- `--worktree`|`-w` *name*[`:`*branch*]:
Apply the change sets inside the dedicated Git worktree
`.ase/worktree/<name>` instead of the current working copy. The
worktree is *reused* if it already exists -- then switched to
*branch* if given and it has no uncommitted changes --, otherwise
it is *created* with the branch *branch* (default: *name*),
checked out if it exists or created from `HEAD` otherwise. One
single worktree serves the whole skill run: it is prepared before
the first discovery, so discovering, grilling, and implementing all
operate on it, all `--loop` iterations land in it, and it is left
uncommitted for review. Unless
`--verify none` is given, the validation then runs as the `ase spec lint` command
inside the worktree. If *name* is a bare lower-case word naming no
existing worktree and a *query* follows (like `-w fix the crash`, a
former boolean `-w` usage), the skill asks whether *name* is the
worktree name or the first query word.
- `--loop`|`-l`:
Loop the whole state cycle: after each iteration, ask for the next
edit query via the interactive `Edit Query` dialog and repeat, until
the user answers with its fixed `STOP SKILL` option or cancels the
dialog.
## ARGUMENTS
- *query*:
Description of the specification edit to perform. When omitted, the
skill asks for the query via an interactive `Edit Query` dialog,
carrying the fixed `STOP SKILL` option plus free-text input.
## SCENARIOS
- You want the specification edited in one shot from a description
- You want `SPEC` changes without the task plan ceremony
- You want the query stress-tested by grilling before the spec is edited
- You want specification edits validated by SpecBook linting
- You want the change set to land on a specific Git branch or worktree
## EXAMPLES
Edit in one shot, without any questions, but with validation:
```text
❯ /ase-spec-edit add a Reviewer persona to the persona model
```
Edit in one shot, without any questions or validation:
```text
❯ /ase-spec-edit -v none add a Reviewer persona to the persona model
```
Grill the query with two rounds first, then edit and fully validate:
```text
❯ /ase-spec-edit -g -r 2 -v full split the Event entity into Event and EventSeries
```
Let the user decide the specification approach in an approach round
first, then edit:
```text
❯ /ase-spec-edit -A model the access permissions of the personas
```
Grill the query with automatically chosen recommended answers, then
edit:
```text
❯ /ase-spec-edit -a add a Reviewer persona to the persona model
```
Grill the query exclusively from the domain perspective, grounded in
the project artifacts and the Internet/Web, then edit:
```text
❯ /ase-spec-edit -g -p domain -G add recurring events to the Event model
```
Loop over multiple specification edits inside a dedicated Git worktree:
```text
❯ /ase-spec-edit -l -w event-series
```
## SEE ALSO
[`ase-spec-activate`](../ase-spec-activate/help.md), [`ase-spec-lint`](../ase-spec-lint/help.md), [`ase-code-edit`](../ase-code-edit/help.md), [`ase-sync-import`](../ase-sync-import/help.md),
[`ase-sync-reconcile`](../ase-sync-reconcile/help.md), [`ase-sync-export`](../ase-sync-export/help.md), [`ase-task-grill`](../ase-task-grill/help.md).