/atn-decompose: break a specification into stages

/atn-decompose splits one specification into one level of stages, asks you the open questions of each stage and leaves every stage Prepared, with the blockers that put them in build order. Run it when a specification covers more than your AI agent should build in one go.

To decompose a specification is to break it down into one level of stages, each a sub-specification of its own. A specification is one described piece of work, with a title, a summary, Markdown content, a status and its own questions and answers. The workflow page shows where decomposition sits between the mind map and the apply run.

Run /atn-decompose

/atn-decompose <spec-id> [--auto-apply]

Argument or flag	Description
<spec-id>	The id of the specification to decompose. Without it, the skill lists the top-level specifications and asks which one.
--auto-apply	Applies the decomposed specification once every stage is Prepared, without asking about the next step. The flag can stand before or after the id.

--auto-apply removes the question about the next step and no other. You answer the questions of each stage, and the apply run asks what it needs to ask.

/atn-decompose <spec-id> --auto-apply

In the web app, a Prepared specification that has no sub-specifications offers Copy decompose command, which copies the command with the id filled in. The page on specifications in the web app shows where to find it.

What /atn-decompose does

1. Asks which specification to decompose, if you gave no id.
2. Reads the specification.
3. Takes the list of stages. If the conversation holds a breakdown, the skill uses it. That is the case when you chose "Decompose into stages" at the end of /atn-mindmap, which proposes the stages and has you confirm them, and when you described the stages yourself. Otherwise the skill asks you to describe the stages.
4. Creates one Draft sub-specification per stage, with a title, a summary and content written from the stage's description and from the parent specification. Where a stage depends on an external API, library or standard, the skill researches it on the web first and lists the sources it used under ## References.
5. Attaches clarifying questions to each stage, each with 2 to 5 options. The questions cover every open decision that would change the stage's scope, its interface or its approach.
6. Asks you the unanswered questions, one stage after another, and records each answer on its stage.
7. Rewrites every stage from its answers and from fresh research into your codebase and your specification tree, and sets each stage to Prepared.
8. Sets the blockers: between the stages, which gives their build order, and from a stage to any other specification it depends on.
9. Reports, then asks what to do next.

A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it.

For a web shop's specification "Checkout flow", the stages are "Cart", "Payment" and "Shipping". After the run, each of the three is a Prepared sub-specification of "Checkout flow" with its own questions and answers, and "Payment" is blocked by "Cart".

One level at a time

The skill works one level below the specification you name. When the mind map proposes the stages, it keeps them coarse for an abstract specification and close in size to the specifications around it in the tree. To go deeper, decompose a stage: choose "Decompose a stage further" at the end of the run, or run /atn-decompose later with the stage's id. A stage that is small enough for an agent to finish in one go stays a leaf specification, which is a specification with no sub-specifications, and leaves are what /atn-apply implements.

Questions /atn-decompose asks

When	The question and its options
No id was given	Which specification to decompose, from the list of top-level specifications. You can type an id that is not on the list.
The conversation holds no breakdown	What the stages are, as an open question
After the stages are created	The clarifying questions of each stage, each with 2 to 5 options
At the end, without --auto-apply	The next step: "Apply now", "Decompose a stage further" or "Nothing else"
After "Decompose a stage further"	Which stages to decompose, as a multiple-choice list of all stages

"Apply now" starts an apply run on the decomposed specification, which implements its stages in the order of their blockers. "Decompose a stage further" runs the skill again on each stage you select, one after another, each with its own questions.

What /atn-decompose changes

Where	What changes
The specification tree	One sub-specification per stage is added under the specification you named.
Each stage	Created as a Draft, then rewritten and set to Prepared. Its title stays as it was created. Its summary changes only when your answers or the research changed its scope.
Questions and answers	The clarifying questions and your answers are stored on each stage, and you read them on the stage's Questions & answers tab. A question you left unanswered is not used in the stage's final content.
Blockers	Each stage gets the blockers the research found, and blockers that the research rejects are removed. The parent's own blockers are not copied to the stages, because every stage inherits them.
The specification you named	Its content and its status stay as they are.
Your repository	Nothing. Decomposition reads your code and writes no file, branch or commit.

A blocker is left out when it points at a Completed specification, at the stage itself, at the parent or another ancestor, or at one of the stage's own sub-specifications. A blocker that Athenode refuses is reported with the reason.

When your methodology setting is tests first, each stage's content also holds an ## Acceptance criteria section wherever testable criteria can be drawn from the stage and your answers. The setting is one of the choices of /atn-settings.

The stages appear in the web app as they are created, and their statuses change there without a reload.

The report

The report gives:

• the id and title of the specification you named, and the id and title of every Prepared stage;
• each stage's blockers, written as "Payment is blocked by Cart" with the blocker's id and status;
• per stage, the blockers that were added, removed and skipped, with the reason for each skipped one;
• after "Decompose a stage further", one combined report with every decomposed stage and the ids and titles of the stages created under it.

With --auto-apply, or after "Apply now", the report of the apply run follows.