Revert the docs re-sync — quoting SKILL.md text and narrating the change was bad documentation

The two FAQ edits quoted the literal new SKILL.md instruction text and
described "now X, replacing Y, intended to fix Z" — implementation-change
narration, exactly what .agents/writing-docs.md's "explain the why, not
the process" / "never reproduces the SKILL.md steps" rules argue against.
It also duplicates content that lives in SKILL.md, which is precisely
what caused the stale quote this PR already had to fix once. That story
belongs in the changeset/CHANGELOG, not the docs page. Reverted both
files to their pre-PR state; the changeset stays as the record of what
changed and why.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
2026-08-15 20:59:36 +00:00
parent e3e547b57d
commit da2cb7d411
2 changed files with 4 additions and 4 deletions
+1 -1
View File
@@ -55,7 +55,7 @@ Scope decides it. Use this for anything you can settle in one session; use [wayf
Two known causes. The mundane one: nothing qualified. ADRs need all three gates, and a session about a change with no new vocabulary genuinely has nothing to write. The real bug: when the skill runs inside another orchestration layer — a spec-driven-development wrapper, a multi-agent framework, a rule that invokes it as a step in someone else's pipeline — the file-writing half is reported to silently not happen, while the interview still runs. This is filed and unfixed. If you are in that setup, check the working directory before you trust the session's output. Two known causes. The mundane one: nothing qualified. ADRs need all three gates, and a session about a change with no new vocabulary genuinely has nothing to write. The real bug: when the skill runs inside another orchestration layer — a spec-driven-development wrapper, a multi-agent framework, a rule that invokes it as a step in someone else's pipeline — the file-writing half is reported to silently not happen, while the interview still runs. This is filed and unfixed. If you are in that setup, check the working directory before you trust the session's output.
**It asked everything at once, with no recommendations, and never mentioned `CONTEXT.md`.** **It asked everything at once, with no recommendations, and never mentioned `CONTEXT.md`.**
That is the skill failing to load its two dependencies. `SKILL.md` is a one-line delegation that now names both explicitly as separate Skill tool calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`") rather than a bare mention, which is intended to raise the hit rate — but an agent that still doesn't pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it has been the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded. That is the skill failing to load its two dependencies. Because `SKILL.md` is a one-line delegation, an agent that does not pick up [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) guesses at what grilling means, and you get an undifferentiated question dump. Partial loading is the more confusing case — `grilling` loads, `domain-modeling` does not, and you get a good interview with no paper trail. It correlates with model and [effort](https://www.aihero.dev/ai-coding-dictionary/effort) level, and it is the most reported problem with this skill. If you suspect it, ask the agent directly which skills it loaded.
**Where did all my other decisions go?** **Where did all my other decisions go?**
Into the conversation only. This is the most substantive open complaint about the skill: the glossary is not a spec, most answers do not earn an ADR, and there is no ledger tying each resolved answer through to a spec, a ticket and a test. Precise answers — ordering guarantees, negative requirements, numeric defaults — get softened into weaker prose downstream, and the result can look complete while missing the thing you actually decided. The mitigation available today is to keep the session and feed it straight to [to-spec](https://aihero.dev/skills-to-spec), and to re-read the spec against your own answers rather than assuming it captured them. Into the conversation only. This is the most substantive open complaint about the skill: the glossary is not a spec, most answers do not earn an ADR, and there is no ledger tying each resolved answer through to a spec, a ticket and a test. Precise answers — ordering guarantees, negative requirements, numeric defaults — get softened into weaker prose downstream, and the result can look complete while missing the thing you actually decided. The mitigation available today is to keep the session and feed it straight to [to-spec](https://aihero.dev/skills-to-spec), and to re-read the spec against your own answers rather than assuming it captured them.
+3 -3
View File
@@ -16,7 +16,7 @@ Typing `/grilling` directly gets you the plain interview and nothing else. Where
| You are in a working directory | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) — the same session, and it writes `CONTEXT.md` and ADRs as it goes | | You are in a working directory | [grill-with-docs](https://aihero.dev/skills-grill-with-docs) — the same session, and it writes `CONTEXT.md` and ADRs as it goes |
| An effort too big to hold in one session | [wayfinder](https://aihero.dev/skills-wayfinder) — it charts a map and runs grilling inside the decision tickets | | An effort too big to hold in one session | [wayfinder](https://aihero.dev/skills-wayfinder) — it charts a map and runs grilling inside the decision tickets |
| A question that talking cannot settle — how something should look or feel | [prototype](https://aihero.dev/skills-prototype) — build the throwaway version, then come back | | A question that talking cannot settle — how something should look or feel | [prototype](https://aihero.dev/skills-prototype) — build the throwaway version, then come back |
| A skill of your own that needs an interview | Call the Skill tool with "grilling" from it, rather than writing another interview | | A skill of your own that needs an interview | Invoke `/grilling` from it, rather than writing another interview |
## The round, the frontier, and who decides ## The round, the frontier, and who decides
@@ -67,10 +67,10 @@ That is a bug in the run, not the intended behaviour, and it was the reason fact
No, and a cap is deliberately out of scope. Some plans need three questions and some need fifty; a fixed ceiling either truncates the hard case or feels arbitrary on the easy one. Steering in plain language is the intended control — tell it to wrap up, or stop and accept the plan where it stands. If a session is running very long, the cause is usually that the scope was too big; break the work up and grill the pieces. No, and a cap is deliberately out of scope. Some plans need three questions and some need fifty; a fixed ceiling either truncates the hard case or feels arbitrary on the easy one. Steering in plain language is the intended control — tell it to wrap up, or stop and accept the plan where it stands. If a session is running very long, the cause is usually that the scope was too big; break the work up and grill the pieces.
**I installed `grill-me` on its own and nothing happens.** **I installed `grill-me` on its own and nothing happens.**
`grill-me` is a one-line skill whose whole body is `Call the Skill tool with "grilling"`, so it needs this skill installed too. The same is true of `grill-with-docs`, which additionally needs [domain-modeling](https://aihero.dev/skills-domain-modeling). Installing the whole set avoids the problem; installing selectively means installing the primitives as well. `grill-me` is a one-line skill whose whole body is "run a `/grilling` session", so it needs this skill installed too. The same is true of `grill-with-docs`, which additionally needs [domain-modeling](https://aihero.dev/skills-domain-modeling). Installing the whole set avoids the problem; installing selectively means installing the primitives as well.
**`grill-with-docs` ran, but it never loaded `grilling`.** **`grill-with-docs` ran, but it never loaded `grilling`.**
A reported rough edge, seen across [harnesses](https://www.aihero.dev/ai-coding-dictionary/harness) and models: a skill that names another skill in prose does not reliably cause that skill to load, and `grill-with-docs` names two. The skill's body now names both explicitly as separate Skill tool calls ("Call the Skill tool twice, for `grilling` and `domain-modeling`") rather than a bare mention, which is intended to raise the hit rate — but if you still see it, the tell is a session that asks everything at once with no recommendations attached, which is the model improvising an interview rather than running this one. Asking the agent directly whether it loaded `grilling` and `domain-modeling` usually recovers it. A real and unfixed rough edge, reported across [harnesses](https://www.aihero.dev/ai-coding-dictionary/harness) and models: a skill that names another skill does not reliably cause that skill to load, and `grill-with-docs` names two. The tell is a session that asks everything at once with no recommendations attached — that is the model improvising an interview rather than running this one. Asking the agent directly whether it loaded `grilling` and `domain-modeling` usually recovers it.
## It's working if ## It's working if