diff --git a/.changeset/wayfinder-situational-onramp.md b/.changeset/wayfinder-situational-onramp.md new file mode 100644 index 0000000..275f99d --- /dev/null +++ b/.changeset/wayfinder-situational-onramp.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": minor +--- + +Settle wayfinder's place in the docs as a **situational on-ramp**, not the new main entry flow — the grill-led *idea → ship* chain stays the front door (crowning wayfinder as the default spine is a v2-sized move, not a 1.1). The **`ask-matt`** router now names wayfinder's concrete triggers — a greenfield project or a huge feature build, too big for one session — and the two grill front doors (**`grill-me`**, **`grill-with-docs`**) signpost *up* to wayfinder for the effort that's too big to hold in one session, so the on-ramp is discoverable from where a reader actually starts. diff --git a/docs/engineering/grill-with-docs.md b/docs/engineering/grill-with-docs.md index e8c4abc..77c1747 100644 --- a/docs/engineering/grill-with-docs.md +++ b/docs/engineering/grill-with-docs.md @@ -20,7 +20,7 @@ The grilling **leaves a paper trail**. A plain interview sharpens your thinking You invoke this by typing `/grill-with-docs` — the agent won't reach for it on its own. -Reach for it at the very start of a change, when the plan is still fuzzy and the domain language isn't settled, and you want to stress-test both before any code exists. If you only want the interview and don't need the artifacts, use [grilling](https://aihero.dev/skills-grilling); if the plan is already clear and you just need to pin down or record terminology, use [domain-modeling](https://aihero.dev/skills-domain-modeling). +Reach for it at the very start of a change, when the plan is still fuzzy and the domain language isn't settled, and you want to stress-test both before any code exists. If you only want the interview and don't need the artifacts, use [grilling](https://aihero.dev/skills-grilling); if the plan is already clear and you just need to pin down or record terminology, use [domain-modeling](https://aihero.dev/skills-domain-modeling). And if the change is too big to hold in one session and its route is still foggy — a greenfield project, a huge feature build — start upstream with [wayfinder](https://aihero.dev/skills-wayfinder): it charts the effort as a map of decisions, then hands back to this main flow once the way is clear. ## Prerequisites diff --git a/docs/productivity/grill-me.md b/docs/productivity/grill-me.md index 7a8e3fb..5a2e6c0 100644 --- a/docs/productivity/grill-me.md +++ b/docs/productivity/grill-me.md @@ -20,7 +20,7 @@ It asks **one question at a time** and waits. It never dumps a batch of question You invoke this by typing `/grill-me` — the agent won't reach for it on its own. -Reach for it before you build, when a plan feels roughly right but you can sense unresolved decisions hiding in it — the moment you want the soft spots found and forced into the open. If you want that same interrogation to also leave a paper trail of ADRs and a glossary behind, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs) instead. +Reach for it before you build, when a plan feels roughly right but you can sense unresolved decisions hiding in it — the moment you want the soft spots found and forced into the open. If you want that same interrogation to also leave a paper trail of ADRs and a glossary behind, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs) instead. And if the effort is too big to hold in one session and the route to the goal is still foggy — a greenfield project, a huge feature build — start further upstream with [wayfinder](https://aihero.dev/skills-wayfinder), which charts it as a map of decisions first and then merges back into this flow. ## The design tree diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 8d90a38..cc1866a 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -41,7 +41,7 @@ A starting situation that generates work, then merges onto the main flow. - **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down. -- **A huge, foggy effort — too big for one session** → **`/wayfinder`**. When the way from here to the destination isn't visible yet, it charts a **shared map** of investigation tickets on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Then it merges onto the main flow at **`/to-spec`** (or, if the effort turned out small enough, straight to **`/implement`**). Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't. +- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**. When the way from here to the destination isn't visible yet, it charts a **shared map** of investigation tickets on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Then it merges onto the main flow at **`/to-spec`** (or, if the effort turned out small enough, straight to **`/implement`**). Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't. ## Codebase health