Skip to content

rse/ase / plugin/skills/ase-spec-edit

ase-spec-edit

Verified

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.

FileKindSize
SKILL.mdskill md23.1 KB
help.mdmarkdown12.9 KB

##  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).
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall