Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/skills/issue-spec/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -547,7 +547,7 @@ For each piece of feedback ask the only question that matters at this altitude:

**Settle on the loop, not on the assertion.** A claim asserted *once* — however confidently, however wrong it sounds — is ordinary triage: answer it, fold it, or drop it with a pointer to the code. The trigger is the **second** pass: the claim came back after being answered, or the spec has already flipped on it, or two rounds reached opposite conclusions. That repetition is the signal prose has failed on it, and it's the one case where another round of argument is predictably wasted. Fire then, and not before — POC-ing every assertion would replace a two-round review with a queue of experiments, which costs more than the debate did.

**The default is Note, and the burden of proof is on folding.** If you can't name which decision card or which part of the approach changes, it isn't spec-level. The one cheap exception: genuine factual corrections and broken references get fixed inline without ceremony — they don't move the design, so they don't cost a round.
**The default is Note, and the burden of proof is on folding.** If you can't name which decision card or which part of the approach changes, it isn't spec-level. The one cheap exception: genuine factual corrections and broken references get fixed inline without ceremony — they don't move the design, so they don't cost a round. Any correction, inline or folded, still owes its echoes: before the push, run [`issue-implement`](../issue-implement/SKILL.md) 10.6's word and surface sweeps over every claim you corrected, and report both.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify nit: §6.5 already sends readers to orchestration as canonical for this bar (line 535). You could replace this full sentence with a short back-pointer (“…including echo sweeps per orchestration → spec-review triage”) and keep a single copy of the obligation text in orchestration.md. Optional — the mirror matches today’s issue-spec/orchestration duplication pattern.


Two instincts to override, because both run the wrong way:

Expand Down
4 changes: 4 additions & 0 deletions .agents/skills/polish-docs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,10 @@ Restructuring breaks links and moves anchors — prove it didn't:
`@docusaurus/plugin-client-redirects`).
- Re-read moved/merged pages once as a reader to confirm the rearrangement flows.

Where the pass changed what a page asserts, not only its wording, sweep every claim you corrected:
run [`issue-implement`](../issue-implement/SKILL.md) 10.6's word and surface sweeps over the docs

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Linking to §10.6 is the right reuse, but that section opens as a PR-feedback gate and later says not to hand-edit apps/docs/ during implement feedback (Step 5C). For polish-docs, you are the docs pass — worth one clause that hits found in docs/READMEs get converged in this PR (not deferred to 5C). Uncertain this belongs in this PR vs a one-line framing tweak in §10.6 for non-implement lifecycles.

and package READMEs, and report both in the PR.

## Output

- **Standalone:** present the working changes for review — a short summary of *what moved, what
Expand Down
4 changes: 3 additions & 1 deletion docs/contributing/orchestration.md
Original file line number Diff line number Diff line change
Expand Up @@ -495,7 +495,9 @@ altitude: *does acting on this change the approach?* Then pick exactly one dispo
name which decision or which part of the approach changes, it is not spec-level —
it's a note. Genuine factual corrections and broken references are the one cheap
exception: fix them inline without ceremony (they don't move the design, so they don't
cost a round).
cost a round). Any correction, inline or folded, still owes its echoes: before the push, run

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“Inline or folded” reaches fold echoes (ledger intent) but sits on the paragraph about the cheap exception. If you ever see agents treating every fold like a repo-wide grep obligation on top of 6.5.2, consider scoping the pointer to inline factual corrections only — I’d wait for evidence before changing.

[`issue-implement`](../../.agents/skills/issue-implement/SKILL.md) 10.6's word and surface
sweeps over every claim you corrected, and report both.

Two things follow that are worth stating outright, because the instinct runs the other way:

Expand Down
Loading