diff --git a/skills/alignment-check/SKILL.md b/skills/alignment-check/SKILL.md index ef63821..343dc85 100644 --- a/skills/alignment-check/SKILL.md +++ b/skills/alignment-check/SKILL.md @@ -25,33 +25,62 @@ Invoked automatically by `writing-plans` in autonomous mode. Can also be invoked ## Dispatching the Alignment Agent -Dispatch a Sonnet agent to perform the comparison: +Dispatch a `balanced`-tier subagent to verify alignment. The subagent reads both documents and produces an Alignment Report: + +**Input:** +- Design document: `docs/plans/YYYY-MM-DD--design.md` +- Implementation plan: `docs/plans/YYYY-MM-DD-.md` + +**Forward trace (design → plan):** +For each requirement in the design: +- Find the plan task(s) that implement it +- If no task covers it: flag as MISSING + +**Reverse trace (plan → design):** +For each task in the plan: +- Find the design requirement it satisfies +- If no requirement justifies it: flag as SCOPE CREEP + +**Report format:** + +### Alignment Report + +**Status:** PASS | FAIL + +**Coverage:** +| Design Requirement | Plan Task(s) | Status | +|---|---|---| +| [requirement] | Task N | ✅ Covered | +| [requirement] | — | ❌ MISSING | + +**Scope Check:** +| Plan Task | Design Requirement | Status | +|---|---|---| +| Task N | [requirement] | ✅ Justified | +| Task N | — | ⚠️ SCOPE CREEP | + +**Drift Items:** [list specific items to fix] + + +Dispatch using the Agent tool: ``` -Agent tool (general-purpose, model: sonnet): +Agent tool (general-purpose, model: balanced): description: "Check alignment: design vs plan" prompt: | You are verifying that an implementation plan aligns with its design document. - ## Design Document - [Read: docs/plans/YYYY-MM-DD--design.md] - - ## Implementation Plan - [Read: docs/plans/YYYY-MM-DD-.md] + Read docs/plans/YYYY-MM-DD--design.md and docs/plans/YYYY-MM-DD-.md. - ## Your Job + Perform a forward trace (design → plan): + - For each requirement, constraint, and acceptance criterion in the design, find the plan task(s) that implement it. + - If no plan task covers a design item, flag it as MISSING. - **Forward trace (design → plan):** - For each requirement in the design: - - Find the plan task(s) that implement it - - If no task covers it: flag as MISSING + Perform a reverse trace (plan → design): + - For each task in the implementation plan, find the design requirement, constraint, or acceptance criterion it satisfies. + - If no design item justifies a plan task, flag it as SCOPE CREEP. - **Reverse trace (plan → design):** - For each task in the plan: - - Find the design requirement it satisfies - - If no requirement justifies it: flag as SCOPE CREEP - - **Report format:** + Return exactly this report format: ### Alignment Report @@ -70,7 +99,14 @@ Agent tool (general-purpose, model: sonnet): | Task N | — | ⚠️ SCOPE CREEP | **Drift Items:** [list specific items to fix] + + Set **Status:** to PASS only if every design item is covered and every plan task is justified. Otherwise set it to FAIL. ``` + + + +Run the alignment check inline: read both documents, perform the forward and reverse traces using the Comparison Procedure above, and produce the Alignment Report. + ## On FAIL diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 7b83cee..de249ad 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -9,7 +9,7 @@ description: "You MUST use this before any creative work - creating features, bu Help turn ideas into fully formed designs and specs through natural collaborative dialogue. -Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval. +Start by understanding the current project context, then ask questions using adaptive batching to refine the idea. Once you understand what you're building, present the design and get user approval. Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity. @@ -24,7 +24,7 @@ Every project goes through this process. A todo list, a single-function utility, You MUST create a task for each of these items and complete them in order: 1. **Explore project context** — check files, docs, recent commits -2. **Ask clarifying questions** — adaptive batching: group 2-4 related questions per form, follow up with targeted singles +2. **Ask clarifying questions** — adaptive batching: group related questions to reduce round-trips; use targeted singles for follow-ups 3. **Propose 2-3 approaches** — with trade-offs and your recommendation 4. **Present design** — in sections scaled to their complexity, get user approval after each section 5. **Write design doc** — save to `docs/plans/YYYY-MM-DD--design.md` and commit @@ -58,11 +58,20 @@ digraph brainstorming { **Understanding the idea:** - Check out the current project state first (files, docs, recent commits) -- Ask questions using adaptive batching with AskUserQuestion: - - **First form:** Group 2-4 related questions covering purpose, constraints, scope, and tech choices - - **Follow-ups:** Targeted single questions based on interesting or ambiguous answers from previous forms +- Ask questions using adaptive batching — group related questions to reduce round-trips: + - **First batch:** covers purpose, constraints, scope, and tech choices + - **Follow-ups:** Targeted single questions based on interesting or ambiguous answers + + - Use multiple choice options when possible (AskUserQuestion supports 2-4 options per question) - AskUserQuestion supports up to 4 questions per form — use this to reduce round-trips + + + + - Present options as a numbered list and ask the user to reply with the chosen number + - Group no more than 3 questions per turn to avoid overloading the chat + + - Focus on understanding: purpose, constraints, success criteria **Exploring approaches:** @@ -106,7 +115,7 @@ When the user wants design exploration without execution, they pass `--design-on ## Key Principles -- **Adaptive question batching** - Group 2-4 related questions per form, follow up with targeted singles +- **Adaptive question batching** - Group related questions to reduce round-trips; use targeted singles for follow-ups - **Multiple choice preferred** - Easier to answer than open-ended when possible - **YAGNI ruthlessly** - Remove unnecessary features from all designs - **Explore alternatives** - Always propose 2-3 approaches before settling diff --git a/skills/pr-monitoring/SKILL.md b/skills/pr-monitoring/SKILL.md index 2ecebe7..eef5374 100644 --- a/skills/pr-monitoring/SKILL.md +++ b/skills/pr-monitoring/SKILL.md @@ -17,10 +17,13 @@ Invoked automatically by `finishing-a-development-branch` in autonomous mode aft ## The Process -Spawn a background agent that monitors the PR in a loop: +Run a `balanced`-tier agent that monitors the PR in a loop until all CI checks pass and no unresolved reviews remain. -``` -Agent tool (general-purpose, model: sonnet, run_in_background: true): + +Use the Agent tool to run the monitor in the background: + +```` +Agent tool (general-purpose, model: balanced, run_in_background: true): description: "Monitor PR #N for CI and reviews" prompt: | You are monitoring PR # on and automatically fixing issues. @@ -33,9 +36,7 @@ Agent tool (general-purpose, model: sonnet, run_in_background: true): Design doc: Plan doc: - ## Monitor Loop - - Repeat until exit conditions met: + Repeat the Monitor Loop until exit conditions are met: ### 1. Check CI Status @@ -88,6 +89,20 @@ Agent tool (general-purpose, model: sonnet, run_in_background: true): ### 4. Wait Between Checks Sleep 60 seconds between check cycles. Do not poll more frequently. +```` + + + + +Use your host's equivalent mechanism to periodically poll the following in a loop: +- `gh pr checks ` — fix any failing CI checks +- `gh api repos///pulls//comments` — respond to inline review comments +- `gh api repos///pulls//reviews` — handle any "CHANGES_REQUESTED" reviews + +Continue until all checks pass, no unresolved inline comments remain, and no "changes requested" reviews are pending. + + + ## Safety Limits