@sassywares/skills 0.6.2 → 0.6.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/package.json +1 -1
- package/skills/sassy-plan/SKILL.md +30 -17
- package/skills/sassy-plan/references/interview.md +87 -0
- package/skills/sassy-plan/references/plan-format.md +19 -2
- package/skills/sassy-plan/references/sketches.md +26 -0
- package/skills/sassy-ship/SKILL.md +0 -1
package/README.md
CHANGED
|
@@ -79,7 +79,7 @@ Debugging:
|
|
|
79
79
|
|
|
80
80
|
| Skill | What it does |
|
|
81
81
|
|---|---|
|
|
82
|
-
| **`sassy-plan`** |
|
|
82
|
+
| **`sassy-plan`** | Grills you one question at a time through every branch of the work — pushing back, assuming nothing, sketching UI on request — until nothing is open, then offers three choices: write the plan, start working now, or take it all the way to a PR. |
|
|
83
83
|
| **`sassy-scout`** | Grounds an area on demand and writes the shared grounding brief other agents read instead of re-exploring. |
|
|
84
84
|
| **`sassy-work`** | Executes exactly one plan phase, or one in-context brief, commits after code approval, then hands off the next phase — a brief stops before ship. |
|
|
85
85
|
| **`sassy-lfg`** | Executes every phase of a plan, or one in-context brief, then closes out via `sassy-ship` after code approval. |
|
package/package.json
CHANGED
|
@@ -1,17 +1,18 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sassy-plan
|
|
3
3
|
description: >-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
Grill the user relentlessly about a piece of work, walking every branch of the
|
|
5
|
+
decision tree until nothing is assumed or open, then let the user choose:
|
|
6
|
+
write a plan document, start working now, or take it all the way to a PR.
|
|
7
|
+
Sketches UI on request. No modes, no QA flags. Use when asked to brainstorm,
|
|
8
|
+
scope, plan, or create a phased plan.
|
|
8
9
|
argument-hint: "[feature description, requirements, or idea to scope]"
|
|
9
10
|
disable-model-invocation: true
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
# Sassy Plan
|
|
13
14
|
|
|
14
|
-
**Outcome:** a
|
|
15
|
+
**Outcome:** a decision ledger with zero open items — every branch of the work resolved by the user, explicitly delegated by them, or explicitly deferred by them — then the user's explicit choice from three options: write a plan document, start working now, or take it all the way to a PR.
|
|
15
16
|
|
|
16
17
|
**Does not implement.** Planning never implements. Execution belongs to `sassy-work` or `sassy-lfg`, and only after the user picks.
|
|
17
18
|
|
|
@@ -19,22 +20,32 @@ disable-model-invocation: true
|
|
|
19
20
|
|
|
20
21
|
**Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
|
|
21
22
|
|
|
22
|
-
##
|
|
23
|
+
## Hard rules
|
|
23
24
|
|
|
24
|
-
|
|
25
|
+
- **Assume nothing.** Your inference is not a decision until the user confirms it. No silent defaults, no "I'll go with X unless you object". A branch is closed only when the user decided it, told you to use your recommendation, or chose to defer it — and each closure is recorded.
|
|
26
|
+
- **One question per turn.** Pick the single question whose answer unblocks the most of the tree. Stacked questions get diluted answers.
|
|
27
|
+
- **Always recommend.** Every question carries your recommended answer and why, so the user can confirm in one word. Recommending is not deciding.
|
|
28
|
+
- **Explore before asking.** If the codebase, config, docs, or a prior learning can answer it, look it up and show the answer with its `file:line` instead of asking. Ask only what the user alone can settle.
|
|
29
|
+
- **Push back.** Challenge thin reasoning, contradictions, and unexamined solution shapes with evidence. Disagree when you disagree. Concede only to an argument or to the user's explicit call — never to fatigue.
|
|
30
|
+
- **No exit with open branches.** "Settled enough" is not settled. The only exits are a ledger with zero open items or the user explicitly ending the interview, in which case every open item becomes a named, user-acknowledged assumption.
|
|
25
31
|
|
|
26
|
-
|
|
27
|
-
- **Find the real constraints.** Existing architecture, conventions, dependencies, and anything that must not change.
|
|
28
|
-
- **Surface the unknown.** Ask only questions whose answer changes the plan. Ask a few at a time, not an interrogation. Offer a recommended default with each so the user can just confirm.
|
|
29
|
-
- **Recon the code.** Use `sassy-scout` to ground the area: relevant files, existing patterns, prior art, and any prior learning written about it. Do not read the whole repo yourself; it writes a grounding brief and returns a gist plus the brief path.
|
|
30
|
-
- **Use the learnings.** When the brief lists prior learnings, treat a relevant one as a constraint on the design and record it as a decision (`D3: …`) so the plan cites it. A learning that contradicts the plan is worth naming at the picker, not discovering mid-phase.
|
|
31
|
-
- **Settle decisions.** As choices become firm, record them as `D1: …`, `D2: …`. These go in the plan or the brief.
|
|
32
|
+
## Phase A — Grill
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
**Read `references/interview.md` first.** It is the decision-tree protocol, the pushback lenses, the coverage sweep, and the ledger format; this section is only the order.
|
|
35
|
+
|
|
36
|
+
1. **Frame.** Restate the goal in one or two sentences and ask the user to confirm or correct it. Ask what they are already thinking before offering your own ideas.
|
|
37
|
+
2. **Ground.** Use `sassy-scout` to ground the area: relevant files, existing patterns, prior art, and prior learnings. It writes a grounding brief and returns a gist plus the brief path; do not read the whole repo yourself. A relevant learning is a constraint — record it as a decision (`D3: …`) so the plan cites it; one that contradicts the user's direction is a pushback, raised now.
|
|
38
|
+
3. **Map the tree.** Lay out the decision tree — every branch you can see, in dependency order — as the open ledger, and show it. The user can add, cut, or reorder branches.
|
|
39
|
+
4. **Walk it.** Resolve branches one question per turn, parents before children. Each answer can open new branches; add them to the ledger as they appear. Apply the pushback lenses as gaps show up, not as a gauntlet.
|
|
40
|
+
5. **Approaches.** When a branch has more than one plausible direction, present 2–3 concrete approaches — at least one non-obvious — with trade-offs, all before your recommendation.
|
|
41
|
+
6. **Sweep.** Before declaring anything settled, run the coverage sweep: flows, states, edge and failure paths, permissions, data, integration seams, rollout, verification. Every item ends decided or marked not applicable with a reason. Then run the integration check for consequences of decisions combined.
|
|
42
|
+
7. **Read back.** Show the full ledger — decisions with provenance, constraints, non-goals, deferred items, assumptions — and ask the user to confirm it is complete and correct. A correction reopens that branch.
|
|
43
|
+
|
|
44
|
+
**UI work.** When a decision is about layout, navigation, states, flow, or interaction shape and the user asks to see it, read `references/sketches.md` and draw it. Say once, at the first such decision, that a sketch is available.
|
|
34
45
|
|
|
35
46
|
## The picker
|
|
36
47
|
|
|
37
|
-
|
|
48
|
+
Only when the read-back is confirmed with zero open items, present exactly these three options and stop until the user picks. Do not recommend one.
|
|
38
49
|
|
|
39
50
|
```text
|
|
40
51
|
Settled. Pick one:
|
|
@@ -43,7 +54,7 @@ Settled. Pick one:
|
|
|
43
54
|
3. Take it all the way — run it, ship it, babysit the PR
|
|
44
55
|
```
|
|
45
56
|
|
|
46
|
-
The user must pick explicitly. There is no default and no auto-selection. If no human is present to answer (rare, e.g. a scripted invocation), take option 2 and say so.
|
|
57
|
+
The user must pick explicitly. There is no default and no auto-selection. If no human is present to answer (rare, e.g. a scripted invocation), take option 2 and say so; every branch you resolved without the user is recorded as an assumption, never as a decision.
|
|
47
58
|
|
|
48
59
|
### Option 1 — Write the plan
|
|
49
60
|
|
|
@@ -63,4 +74,6 @@ The plan document carries manual QA tables per `references/plan-format.md`. Thos
|
|
|
63
74
|
|
|
64
75
|
## Resume
|
|
65
76
|
|
|
66
|
-
If the user points at an existing sassy plan, update phases and tables in place. If they point at a raw plan from elsewhere, reshape it into this format without discarding its settled decisions. An existing plan is already the document.
|
|
77
|
+
If the user points at an existing sassy plan, update phases and tables in place. If they point at a raw plan from elsewhere, reshape it into this format without discarding its settled decisions — but grill whatever it leaves open or merely asserts. An existing plan is already the document.
|
|
78
|
+
|
|
79
|
+
Decisions the user already made earlier in the conversation, with the trade-off in view, are settled: carry them forward and never re-ask. A bare assertion nobody examined gets exactly one challenge per `references/interview.md`.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Interview protocol
|
|
2
|
+
|
|
3
|
+
Read this before the first question. It is how Phase A grills: the ledger, the question discipline, the pushback lenses, and the coverage sweep that has to come back clean before the picker.
|
|
4
|
+
|
|
5
|
+
## The ledger
|
|
6
|
+
|
|
7
|
+
The ledger is the decision tree made visible. Keep it current and show it whenever it changes shape — at the map, after a branch opens new children, and at the read-back.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
Open
|
|
11
|
+
- O1: Who can send invitations? (blocks O3)
|
|
12
|
+
- O2: What happens when the invitee already has an account?
|
|
13
|
+
- O3: Can an admin revoke a pending invite? (needs O1)
|
|
14
|
+
|
|
15
|
+
Settled
|
|
16
|
+
- D1: Invites expire after 7 days (user-directed, over "never expire": stale links leak access)
|
|
17
|
+
- D2: Reuse the existing mailer (from code: src/mail/send.ts:12)
|
|
18
|
+
|
|
19
|
+
Deferred
|
|
20
|
+
- F1: Bulk CSV invites — next phase (user-deferred)
|
|
21
|
+
|
|
22
|
+
Assumptions
|
|
23
|
+
- A1: Single workspace per invite (user-delegated: "use your call")
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Every item closes into exactly one bucket, with provenance:
|
|
27
|
+
|
|
28
|
+
| Provenance | Meaning |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `user-directed` | The user chose against or between options you surfaced. Name the rejected option and the reason. |
|
|
31
|
+
| `user-approved` | You recommended with the trade-off shown; the user agreed. |
|
|
32
|
+
| `user-delegated` | The user explicitly said to use your recommendation. Lands in Assumptions so it stays visible. |
|
|
33
|
+
| `user-deferred` | The user chose to decide later. Lands in Deferred, with when or by whom. |
|
|
34
|
+
| `from code` | The repo answered it. Cite `file:line`. Shown to the user, never closed off-screen. |
|
|
35
|
+
|
|
36
|
+
Nothing you inferred alone gets a label. "Sounds good" to a passing mention is at most `user-approved`, never `user-directed`. If you cannot name what an item was chosen over, it was not examined — it is still open.
|
|
37
|
+
|
|
38
|
+
## Asking
|
|
39
|
+
|
|
40
|
+
- **One question per turn**, the one that unblocks the most of the tree. Parents before children: do not ask how revocation works before you know who can invite.
|
|
41
|
+
- **Recommend every time.** State your answer and the one reason that matters here. The user confirms in a word or overrides.
|
|
42
|
+
- **Prefer a choice when real options exist.** Use the harness's blocking question tool if it has one (`AskUserQuestion` in Claude Code, `ask_user` in pi); otherwise give numbered options in chat. Put your recommendation first and say so. Use an open question when the answer is a story — evidence, current workaround, who the user is — or when you could not write 2–4 distinct, defensible options without padding.
|
|
43
|
+
- **Be concrete.** Name the scenario. "When the invitee's email already belongs to a member of another workspace, do we merge, reject, or add a second membership?" — not "what about existing users?".
|
|
44
|
+
- **Explore first.** Anything the repo can answer, look up. Show the found answer and its citation as settled ground so the user can object; do not spend a turn on it.
|
|
45
|
+
|
|
46
|
+
## Pushback
|
|
47
|
+
|
|
48
|
+
You are a thinking partner, not a form. Raise each lens as its gap appears, one probe per gap, folded into the walk — never as an up-front checklist. A crisp opening may earn none; a fuzzy one earns several.
|
|
49
|
+
|
|
50
|
+
- **Evidence.** The need is asserted, not shown. Ask for the most concrete thing someone has already done about it — time spent, a workaround built, a complaint filed.
|
|
51
|
+
- **Specificity.** The user is "users". Ask for a specific person or narrow segment and what changes for them when this ships.
|
|
52
|
+
- **Counterfactual.** Ask what people do today when this comes up, and what it costs them if nothing ships.
|
|
53
|
+
- **Attachment.** The request names a solution shape, not the value it delivers. Ask for the smallest version that still delivers that value, and offer one.
|
|
54
|
+
- **Contradiction.** Two answers conflict, or an answer conflicts with the code, a convention, or a prior learning. Quote both sides and ask which wins.
|
|
55
|
+
- **Directive.** A bare "do it with X" that nobody examined gets exactly one challenge, backed by evidence: what X costs here and the strongest alternative. Whatever the user then chooses is settled — do not re-litigate it.
|
|
56
|
+
- **Scope creep.** A "while we're at it" addition gets the same scrutiny as the core: does it need to ship with this, or is it a deferred item?
|
|
57
|
+
- **Higher-upside option.** When an adjacent reframing would make the work clearly more valuable without much carrying cost, put it on the table as a challenger, not a default.
|
|
58
|
+
|
|
59
|
+
**Can't evaluate vs hasn't decided.** If the user answers "I don't know" or "whatever you think" twice in a row on territory they can't judge, stop asking naked questions. Map that territory instead: 3–7 decisions or hazards, each with the realistic options, the trade-off that matters here, and your recommendation. Then ask which they want to walk through. Anything they skip becomes `user-delegated` — written down, never silently assumed. A user who understands the options but hasn't picked gets the normal question, not a lecture.
|
|
60
|
+
|
|
61
|
+
## Coverage sweep
|
|
62
|
+
|
|
63
|
+
Before the read-back, walk this list against the settled tree. Every applicable row needs a decision; every other row needs "N/A — <reason>" said out loud. Do not skip a row silently. Ask about the gaps one at a time, as usual.
|
|
64
|
+
|
|
65
|
+
| Area | Questions it forces |
|
|
66
|
+
|---|---|
|
|
67
|
+
| Actors | Who uses it, who administers it, who must never reach it? |
|
|
68
|
+
| Flows | For each journey: entry point, decision points, happy path, every terminal state (success, error, cancel, timeout). |
|
|
69
|
+
| States | Empty, loading, partial, error, success, stale, offline — which exist and what each shows. |
|
|
70
|
+
| Edge and failure paths | Bad input, duplicates, limits, rate limits, retries, partial failure, concurrency, a dependency down. |
|
|
71
|
+
| Permissions | Role boundaries, ownership, what each role sees and can do. |
|
|
72
|
+
| Data | New or changed shapes, migration, backfill, backward compatibility, retention, deletion. |
|
|
73
|
+
| Integration seams | Every place this touches existing features — what each handoff expects. |
|
|
74
|
+
| Non-functional | Performance, security, privacy, accessibility, i18n — only where they bear on this work. |
|
|
75
|
+
| Rollout | Flag or not, order of release, rollback, who is told. |
|
|
76
|
+
| Verification | Done-when for the whole and per slice; what the user will check by hand. |
|
|
77
|
+
| Non-goals | What this deliberately does not do, so the work cannot drift into it. |
|
|
78
|
+
|
|
79
|
+
**Integration check.** Then combine what was decided and look for consequences no single answer showed: "invites expire in 7 days (D1) and revoking deletes the record (D4), so a revoked link and an expired link show the same error — intended?" One probe per real combined effect.
|
|
80
|
+
|
|
81
|
+
**Implementation-time unknowns** — exact helper names, final query shape, anything only touching the code can answer — are not open branches. Name them in Deferred as implementation-time, with the user's agreement, so they are visible rather than pretended away. Anything that would change behavior, scope, or the done-when is not an implementation detail; it gets asked.
|
|
82
|
+
|
|
83
|
+
## Read-back
|
|
84
|
+
|
|
85
|
+
Show the whole ledger: decisions with provenance, constraints, non-goals, deferred items, assumptions — and an empty Open bucket. Ask one question: is this complete and correct? A correction reopens that branch and the walk resumes there. Only a confirmed read-back with zero open items reaches the picker.
|
|
86
|
+
|
|
87
|
+
If the user ends the interview early, every open item moves to Assumptions with your recommended answer, the user sees that list, and the picker follows. That is their explicit call, not your shortcut.
|
|
@@ -2,6 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
Read this before writing the plan file.
|
|
4
4
|
|
|
5
|
+
## No open questions
|
|
6
|
+
|
|
7
|
+
The plan has no open-questions section. Every branch the interview found is a decision, a deferred item, or an assumption — copy the ledger as it stood at the confirmed read-back. If you find an open branch while writing, stop and ask it before the file lands.
|
|
8
|
+
|
|
5
9
|
## Phase splitting rules
|
|
6
10
|
|
|
7
11
|
1. **Vertical first.** Prefer "ship a thin slice of feature X across all its layers" over "do all the database, then all the API, then all the UI".
|
|
@@ -29,12 +33,25 @@ The user may ask in plain language to omit QA tables for this plan, in which cas
|
|
|
29
33
|
One short paragraph: what we are building and why.
|
|
30
34
|
|
|
31
35
|
## Decisions
|
|
32
|
-
- D1: …
|
|
33
|
-
- D2: …
|
|
36
|
+
- D1: … (user-directed, over <alternative>: <reason>)
|
|
37
|
+
- D2: … (from code: `path/to/file.ts:12`)
|
|
38
|
+
|
|
39
|
+
Every decision carries its provenance from the interview ledger.
|
|
34
40
|
|
|
35
41
|
## Constraints
|
|
36
42
|
Anything that must not change, non-goals, and risks. (Omit if none.)
|
|
37
43
|
|
|
44
|
+
## Deferred
|
|
45
|
+
- F1: … (user-deferred — <when or by whom>)
|
|
46
|
+
- F2: … (implementation-time — <what only the code will answer>)
|
|
47
|
+
|
|
48
|
+
(Omit if none.)
|
|
49
|
+
|
|
50
|
+
## Assumptions
|
|
51
|
+
- A1: … (user-delegated)
|
|
52
|
+
|
|
53
|
+
Items the user handed to the agent's recommendation, or left open when they ended the interview. (Omit if none.)
|
|
54
|
+
|
|
38
55
|
## Phase tracking
|
|
39
56
|
|
|
40
57
|
| Phase | Goal | Status |
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Sketches
|
|
2
|
+
|
|
3
|
+
Read this when the user asks to see a UI decision. A sketch is a throwaway picture that answers one question — which layout, which state, where a step sits in a flow. It is not a design, a prototype, or a spec.
|
|
4
|
+
|
|
5
|
+
## When
|
|
6
|
+
|
|
7
|
+
Only on request. Say once, at the first layout, navigation, state, flow, or interaction-shape decision, that you can sketch it; after that, sketch whenever the user asks. Never sketch product goals, scope, or anything easier to settle in a sentence.
|
|
8
|
+
|
|
9
|
+
## Medium
|
|
10
|
+
|
|
11
|
+
Pick the cheapest one that answers the question.
|
|
12
|
+
|
|
13
|
+
- **In chat (default).** ASCII wireframes or a mermaid flow, side by side as A / B / C. Good for layout structure, flow order, and state lists. Works in every harness.
|
|
14
|
+
- **In a browser.** When the decision depends on proportion, density, or an interaction a text grid cannot show — or the user asks for it. Write one self-contained HTML file (inline CSS, no network, no build) per decision under the `scratch/` temp folder from the `sassy-setup` skill's `references/harness.md`, named `<timestamp>-sketch-<decision>.html`. Open it with the platform opener (`open` on macOS, `xdg-open` on Linux), or give the user the absolute path when you cannot.
|
|
15
|
+
|
|
16
|
+
Match the project's existing UI where the grounding brief shows it — its layout primitives and component names — so the options are realistic. Stay grayscale and low-fidelity: boxes, labels, real copy where copy is the decision. No branding, final colors, typography choices, or animation unless the decision is about exactly that.
|
|
17
|
+
|
|
18
|
+
## Shape
|
|
19
|
+
|
|
20
|
+
- Label every sketch **directional** and say what to judge and what to ignore: "Judge where the invite form sits; ignore spacing and styling."
|
|
21
|
+
- Show 2–3 genuinely different options for one decision, not variations of one. Mark the one you recommend and why.
|
|
22
|
+
- One decision per sketch. A second question gets a second sketch.
|
|
23
|
+
|
|
24
|
+
## Feedback
|
|
25
|
+
|
|
26
|
+
The sketch is display-only; the decision happens in chat. Ask with the blocking question tool when there is one: "A, B, C, or a mix — and what feels off?" Record the answer in the ledger like any other decision, citing the sketch (`D7: Inline invite form, option B of the sketch`). Delete the files once the decision is recorded unless the user wants to keep them.
|
|
@@ -7,7 +7,6 @@ description: >-
|
|
|
7
7
|
waits before anything is written, committed, pushed, or opened. `mode:auto`
|
|
8
8
|
runs the close-out with no review.
|
|
9
9
|
argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit] [base:<branch>] [merge:on|off] [delete-branch:on|off] [mode:manual|auto]"
|
|
10
|
-
disable-model-invocation: true
|
|
11
10
|
---
|
|
12
11
|
|
|
13
12
|
# Sassy Ship
|