stack-dev/stack-close skill split; publish stack-machinery note; model-selection fix (#47 Block 2)
Files changed: - CHANGES.md - VERSION - instructions/claude-code-model-selection.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - tools/CONTRACT.md - tools/chemenu/commands/git_publish.py - tools/chemenu/tests/test_git_publish.py
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
---
|
||||
name: stack-close
|
||||
description: Close out a stack-dev work package after its publish has landed - rewrite the issue body to its final state, check for docs/ staleness, and name which model ran which phase of the session. Use right after a stack-dev session's tools/wikitool publish succeeds, or when resuming a package that was published but never closed.
|
||||
---
|
||||
|
||||
# Stack Close
|
||||
|
||||
**Purpose:** Carry out the unchecked closing phase of a stack-development work package, as its
|
||||
own skill rather than a break `stack-dev` has to remember to ask for mid-flow.
|
||||
|
||||
**Trigger:** A `stack-dev` session's `tools/wikitool publish` just succeeded - `stack-dev` ends
|
||||
there and hands off here rather than continuing into this phase in the same breath. Also: `publish`
|
||||
printed its stack-machinery note ("this publish touched stack machinery...") and nothing has
|
||||
closed the work package it belongs to yet; or a package was published in an earlier session and
|
||||
never went through this skill (the gap this split exists to make impossible to skip past
|
||||
silently - see [issue-tracking.md](../issue-tracking.md)'s note that a closed body is the version
|
||||
everyone reads afterwards and nobody revisits).
|
||||
|
||||
**This directory is dev-only.** Same boundary as `stack-dev`
|
||||
([its own note](../stack-dev/SKILL.md) has the full reasoning) - `dist export` prunes
|
||||
`instructions/dev/` wholesale, so this skill never reaches a distributed instance.
|
||||
|
||||
## Why this is a separate skill, not `stack-dev`'s step 6
|
||||
|
||||
The two phases around the mechanical middle of a stack-dev session have no mechanical guard at
|
||||
all - `pytest`, `docs verify` and `instructions verify` cover the code and tests in between, and
|
||||
nothing covers a changelog entry's accuracy, a `docs/` page's staleness, or an issue body's final
|
||||
state (see [claude-code-model-selection.md](../../claude-code-model-selection.md)). Asking the
|
||||
same session to notice it has crossed into that second unchecked stretch - as a prose break inside
|
||||
`stack-dev`'s own step 6 - failed twice in a row on this stack (Gitea #42, then #30): both times
|
||||
the session knew the rule and skipped past it anyway, because nothing in the moment forced the
|
||||
question. Splitting the phase into its own skill does not add a check either - `wikitool` still
|
||||
does not know this tracker exists and must not learn (see
|
||||
[issue-tracking.md](../issue-tracking.md) § What no tool checks) - but it removes the thing that
|
||||
was actually failing: there is no longer a "next step" to skip past, only a skill nobody has
|
||||
invoked yet. See Gitea #47 for the full incident history and the rejected alternative (a
|
||||
model-switched subagent - not buildable in Claude Code, where a fork inherits the parent's model
|
||||
and a fresh subagent starts without the session's context).
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Offer the model switch back up, once, and keep working either way.**
|
||||
|
||||
> Ab hier greift kein maschineller Check mehr - Issue-Body, `docs/`-Veralterung und
|
||||
> Changelog-Prosa prüft nichts. Wenn du zurück auf Opus willst, ist jetzt der Moment.
|
||||
|
||||
**Never block on the answer.** The change is already published; a session that stops here
|
||||
leaves exactly the state this skill exists to prevent.
|
||||
|
||||
2. **Rewrite the issue body to its final state, then close.** The test is what a reader who
|
||||
opens the closed issue tomorrow would conclude:
|
||||
|
||||
- every acceptance criterion ticked, or struck with the reason it was dropped
|
||||
- proposals that were decided read as decided; a "to decide" section has become the decision
|
||||
and its reasoning
|
||||
- nothing left in the present tense about a defect that no longer exists
|
||||
- what was verified is named - which checks ran, which CI run - not a commit hash alone
|
||||
|
||||
Then one short comment naming what changed against the previous state, and nothing else -
|
||||
[issue-tracking.md](../issue-tracking.md) steps 2-3 and 7 have the full shape; this is that
|
||||
procedure, run at the point this skill exists to guarantee it actually gets run.
|
||||
|
||||
**A closing report in a comment does not satisfy this**, however thorough: it reads as
|
||||
complete to whoever writes it and leaves a body still phrased as open work. Nothing mechanical
|
||||
catches it, which is why this is a step - and now a whole skill - rather than a habit. #44 and
|
||||
#45 both closed exactly this way on the old, single-skill shape, the second an hour after the
|
||||
rule was first written down.
|
||||
|
||||
3. **Check whether a `docs/` page or new human doc went stale.** A `docs/` page carries no
|
||||
normative sentence, so nothing verifies it by construction (AGENTS.md § File naming) - the
|
||||
same is true of `README.md`/`INSTALL.md`/`DEVELOPMENT.md` prose and a new instruction's own
|
||||
wording, which `instructions verify` checks structurally but never for what it claims. If the
|
||||
change this package shipped moved the reasoning one of these pages documents, update it now;
|
||||
if none did, say so rather than leaving the question unasked.
|
||||
|
||||
4. **Name which model ran which phase - not only this one.** This is the handover in full, not
|
||||
a note about the tail alone: state the model for the design/version-part/boundary-judgment
|
||||
phase (`stack-dev` step 3), for the mechanical middle (code, tests, the version bump), and for
|
||||
this closing phase - all three, even when they are all the same model. A handover that only
|
||||
flags a cheap-model *closing* phase stays silent exactly when the earlier, equally unchecked
|
||||
design phase also ran cheap and nobody offered the switch back then either; naming all three
|
||||
every time is what keeps that omission from being the quiet default.
|
||||
|
||||
## Decision points
|
||||
|
||||
- **The work package spans several sessions?** Run this skill once, at the point the package is
|
||||
actually finished and its last publish has landed - not after every individual publish. A
|
||||
package still open across sessions keeps its body current per
|
||||
[issue-tracking.md](../issue-tracking.md) step 2 in the meantime; that is maintenance, not
|
||||
closing.
|
||||
- **Resuming a package whose publish landed in an earlier, already-ended session?** Run this
|
||||
skill now, on whatever model the current session is - do not reopen the earlier session to run
|
||||
it "correctly." The handover in step 4 names the earlier phases from the historical record
|
||||
(the issue's comments, `CHANGES.md`) rather than from memory.
|
||||
- **Nothing to close - the session's own exploration, no publish happened?** This skill does not
|
||||
apply; there is no package to rewrite a body for.
|
||||
|
||||
## Scope
|
||||
|
||||
Follows a `stack-dev` session's publish. Not for wiki content work - use
|
||||
`wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/`wiki-status` for that, whose own closing
|
||||
conventions (`kb/log.md`, page provenance) are unrelated to this tracker-body procedure.
|
||||
@@ -46,9 +46,10 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
package, labelled `area/`, `kind/`, `prio/` and `size/`. There is no `TODO.md`. **The body
|
||||
of the issue you are working on is this session's plan file:** keep it current as the state
|
||||
moves, so an interrupted session leaves a body the next one can resume from, *and* rewrite it
|
||||
to its final state before closing. Both halves bind; the second is step 6 below. Read it
|
||||
before filing something for later, before editing or closing an issue, or before deciding
|
||||
what to pick up next.
|
||||
to its final state before closing. Both halves bind; the second is what
|
||||
[`stack-close`](../stack-close/SKILL.md) carries out once this skill's own work is published -
|
||||
see step 5 below. Read it before filing something for later, before editing or closing an
|
||||
issue, or before deciding what to pick up next.
|
||||
[testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
|
||||
empty machine; what the autouse fixture already neutralizes, and what a test still has to
|
||||
establish itself. Read it before adding or changing a test.
|
||||
@@ -63,14 +64,18 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
list grows without needing this skill file to change shape.
|
||||
3. **Settle the design before building - and break there for the model switch.** These are two
|
||||
different kinds of work, and the split is not stylistic: design, the version part and any
|
||||
boundary judgment have **no** mechanical guard, while the code and tests that follow have
|
||||
`pytest`, `docs verify`, `instructions verify` and CI behind them.
|
||||
boundary judgment have **no** mechanical guard, while the code and tests that follow are mostly
|
||||
covered - `pytest`, `docs verify`, `instructions verify` and CI catch a mistake **in what they
|
||||
cover**.
|
||||
|
||||
So when the design is settled - the issue body says what will be built, the open questions are
|
||||
answered - stop and say so, in one sentence:
|
||||
answered - stop and say so, in one sentence that names what the mechanical stretch does **not**
|
||||
cover:
|
||||
|
||||
> Der Plan steht, ab hier ist die Arbeit mechanisch und durch Tests/CI abgedeckt. Wenn du auf
|
||||
> Opus bist, ist jetzt der Moment für `/model sonnet` bei Effort `high`.
|
||||
> Der Plan steht, ab hier ist die Arbeit größtenteils mechanisch und durch Tests/CI abgedeckt -
|
||||
> mit Ausnahme der Changelog-Prosa (Schritt 4), einer berührten `docs/`-Seite, neuer
|
||||
> Menschendoku oder des Prosa-Anteils einer Instruction. Wenn du auf Opus bist, ist jetzt der
|
||||
> Moment für `/model sonnet` bei Effort `high`.
|
||||
|
||||
**You cannot make this switch yourself** - the session's model is the user's `/model`, not a
|
||||
setting an agent applies. Offer it once and keep working either way; a session that argues
|
||||
@@ -78,6 +83,15 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
be settled after all - a boundary crossing surfaces, an assumption breaks - that is a reason to
|
||||
offer the switch back up, not to decide it alone.
|
||||
|
||||
**"Covered by tests" means covered by the tests that exist, not by the tests that should
|
||||
exist.** Whether the right test was written is itself a judgment call with no mechanical
|
||||
guard: two data-destroying bugs in `upstream merge` (Gitea #30) shipped past a green
|
||||
`pytest`/`docs verify`/`instructions verify`/CI because no test exercised the case, not
|
||||
because a weaker model wrote worse code for the case that *was* tested. This is not a third
|
||||
break - it is a caveat on this one: the middle phase stays the cheaper phase to run on, but its
|
||||
test suite is only as complete as the judgment that wrote it, and that judgment is unchecked
|
||||
the same way the design phase is.
|
||||
|
||||
Effort is the cheaper lever than the model, and `high` is the floor for anything touching more
|
||||
than one file or a contract. Full table and reasoning:
|
||||
[claude-code-model-selection.md](../../claude-code-model-selection.md).
|
||||
@@ -119,47 +133,23 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
Prose-only changes (`README.md`, `INSTALL.md`, `EVALS.md`) and the workflows under `.gitea/`
|
||||
do not need a bump - CI's version gate is scoped to what changes behaviour.
|
||||
|
||||
5. **Verify before publishing.** `tools/wikitool docs verify`, `tools/wikitool instructions
|
||||
verify`, and the relevant `pytest` run in `tools/` - the same checks any stack change must
|
||||
pass, run explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a
|
||||
full `setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves
|
||||
`VERSION` additionally triggers a tagged release. **CI does the tagging** - a session never
|
||||
creates a tag, which is what keeps AGENTS.md invariant 5 intact.
|
||||
5. **Verify, then publish.** `tools/wikitool docs verify`, `tools/wikitool instructions verify`,
|
||||
and the relevant `pytest` run in `tools/` - the same checks any stack change must pass, run
|
||||
explicitly rather than assumed. CI (`.gitea/workflows/ci.yml`) runs these plus a full
|
||||
`setup-instance.md` replay against a fresh `dist export`; a push to `main` that moves `VERSION`
|
||||
additionally triggers a tagged release. **CI does the tagging** - a session never creates a
|
||||
tag, which is what keeps AGENTS.md invariant 5 intact.
|
||||
|
||||
6. **Close the issue with a body rewrite, not a comment.** The last act of a session that
|
||||
finished a work package, and the one most easily skipped: by here the change is published and
|
||||
the issue feels done. It is not. The body is the version everyone reads afterwards and nobody
|
||||
revisits, so it is the one place the debt comes due at the worst moment.
|
||||
Publish with `tools/wikitool publish`. When the changeset touches `tools/`, `types/`,
|
||||
`instructions/`, `AGENTS.md` or a `<stage>/CONTRACT.md`, `publish` itself prints a one-line
|
||||
reminder that the phase past this point is not covered by any of the checks above - that line
|
||||
is the cue that this skill's own job just ended.
|
||||
|
||||
**Break here too, in the other direction.** Everything left in the session - this rewrite,
|
||||
whether a `docs/` page's reasoning went stale, the changelog prose - is the unchecked kind of
|
||||
work again, the mirror of step 3. If the session dropped to Sonnet there, say so now:
|
||||
|
||||
> Ab hier greift kein maschineller Check mehr - Issue-Body, `docs/`-Veralterung und
|
||||
> Changelog-Prosa prüft nichts. Wenn du zurück auf Opus willst, ist jetzt der Moment.
|
||||
|
||||
Then **do the work regardless of the answer.** Never block a close on a model switch: the
|
||||
change is already published, and a session that stops here leaves exactly the state this step
|
||||
exists to prevent. If it ran on the cheaper model, name that in the handover rather than
|
||||
leaving it silent.
|
||||
|
||||
Rewrite it to its final state *first*, then close. The test is what a reader who opens the
|
||||
closed issue tomorrow would conclude:
|
||||
|
||||
- every acceptance criterion ticked, or struck with the reason it was dropped
|
||||
- proposals that were decided read as decided; a "to decide" section has become the decision
|
||||
and its reasoning
|
||||
- nothing left in the present tense about a defect that no longer exists
|
||||
- what was verified is named - which checks ran, which CI run - not a commit hash alone
|
||||
|
||||
Then one short comment naming what changed against the previous state, and nothing else.
|
||||
|
||||
**A closing report in a comment does not satisfy this**, however thorough: it reads as
|
||||
complete to whoever writes it and leaves a body still phrased as open work. Nothing
|
||||
mechanical catches it - `wikitool` does not know this tracker exists and must not learn it,
|
||||
since it ships to instances that have no board - so this step is the only enforcement there
|
||||
is. #44 and #45 both closed exactly this way, the second an hour after the rule was written.
|
||||
[issue-tracking.md](../issue-tracking.md) step 7 has the full shape.
|
||||
**This skill stops here.** The closing phase - rewriting the issue body to its final state,
|
||||
checking for `docs/` staleness, and naming which model ran which phase of the session - lives
|
||||
in [`stack-close`](../stack-close/SKILL.md), not in a further step of this one. Invoke it now;
|
||||
do not fold its work into this session under this skill's rules, and do not treat "the change
|
||||
is published" as this work package being done.
|
||||
|
||||
## Decision points
|
||||
|
||||
@@ -180,4 +170,5 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
|
||||
|
||||
Not for wiki content work - use `wiki-ingest`/`wiki-query`/`wiki-manage`/`wiki-lint`/
|
||||
`wiki-status` for that. Not for setting up a new instance (`instructions/setup-instance.md`) or
|
||||
a fresh clone of this repo (`instructions/bootstrap.md`).
|
||||
a fresh clone of this repo (`instructions/bootstrap.md`). Not for closing a work package after
|
||||
its publish has landed - that is [`stack-close`](../stack-close/SKILL.md).
|
||||
|
||||
Reference in New Issue
Block a user