ryzizub · Sep 21, 2026 · Oct 7, 2026
@@ -51,11 +51,34 @@ skills/                # User-invocable and supporting skills (one dir per skill
   rebase/SKILL.md                # Sync a feature branch with its base
   elements-of-style/SKILL.md     # Apply Strunk's Elements of Style to prose
   shared/              # Shared references and scripts used across skills
-    references/        # Plan templates, review procedures, handoff steps
+    references/
+      clear-context-handoff.md   # The "clear context and <next step>" handoff block
+      drive-to-green.md          # Loop until every gate is green by real output
+      feature-branch.md          # Branch check run before anything is written to disk
+      file-findings-on-pr.md     # Post review findings as PR comments
+      plan-review.md             # Quality pass applied to a drafted plan
+      plan-templates/            # minimal, standard, extensive, phases, success criteria
+      review-agent-instructions.md  # Instructions passed to each review agent
+      review-consolidation.md    # Deduplicate, order, and number findings
+      review-dispatch.md         # Caller-side procedure for launching review agents
+      review-report-template.md  # Shape of the consolidated report
+      validate-and-fix.md        # Run linter and tests, fix, retry up to 3 times
     scripts/           # detect-base-branch.sh, detect-review-scope.sh
 ```
 
-Each skill directory may also carry a `references/` folder (deeper procedure docs) and a `scripts/` folder (helper shell scripts).
+Each skill directory may also carry a `references/` folder (deeper procedure docs) and a `scripts/` folder (helper shell scripts). A shared reference appears in each consuming skill as a symlink, so the skill always links it by its own local path.
+
+## Authoring Conventions
+
+A `SKILL.md` carries the workflow and the opinions behind it; everything else is demoted to
+`references/` or cut. Before adding or trimming a section, apply the KEEP / DEMOTE / DELETE
+rubric in `CONTRIBUTING.md` → _What belongs in a `SKILL.md`_. Two rules it is easy to get
+backwards:
+
+- The frontmatter `description` is the router and loads before the body, so it carries the
+  whole trigger surface. Never trim it for length, and never split it across a second field.
+- An agent's `description` is paid for on every request, run or not. Keep it expressive and
+  free of `<examples>` blocks (`CONTRIBUTING.md` → _Agent descriptions_).
 
 ## Philosophy
 

@@ -36,7 +36,7 @@ argument-hint: "feature or idea to explore"
 | ----- | -------- | ----- |
 | `name` | Yes | Lowercase letters, numbers, and hyphens only |
 | `user-invocable` | Yes | `true` if the user can invoke this skill directly, `false` otherwise |
-| `description` | Yes | Describes when the skill should be triggered |
+| `description` | Yes | What the skill does **and** when to trigger it. This is the whole trigger surface — there is no separate `when_to_use` field |
 | `argument-hint` | No | Placeholder hint shown to the user |
 
 After the frontmatter, structure the file as:
@@ -68,11 +68,66 @@ Add the new skill directory and its files to the repository structure tree in `A
 - **Provide complete, copy-pasteable snippets** — not fragments.
 - **Reference packages by full name** (e.g., `package:mocktail`, not just "mocktail").
 - **Show anti-patterns alongside correct patterns** when helpful, so readers understand both what to do and what to avoid.
-- **Keep prose tight** — every word in a SKILL.md consumes tokens in the model's context window. Verbose instructions reduce the space available for the user's actual work. Apply these techniques:
-  - **Decision tables over prose chains** — replace long if/else narratives with a table or compact bulleted list.
-  - **One sentence per rule** — if a guideline needs a paragraph to explain, it may be too complex or doing too much.
-  - **Cut redundancy** — don't restate in an "Important" footer what the body already says.
-  - **Collapse conditional blocks** — when multiple branches share structure, describe the shared part once and list only what differs.
+- **Decision tables over prose chains** — replace long if/else narratives with a table or compact bulleted list.
+- **One sentence per rule** — if a guideline needs a paragraph to explain, it may be too complex or doing too much.
+- **Collapse conditional blocks** — when multiple branches share structure, describe the shared part once and list only what differs.
+- **Apply the KEEP / DEMOTE / DELETE rubric below** to decide what earns a place in the `SKILL.md` at all.
+
+## What belongs in a `SKILL.md`
+
+A skill earns its tokens by carrying what the model *cannot* infer: the workflow's decision
+points and the opinions this team holds about them. Generic advice the model already applies
+displaces those opinions and slows routing.
+
+Every section you write gets one of three verdicts.
+
+**KEEP in `SKILL.md`** — the workflow, and the judgement calls it encodes:
+
+- Gates and their thresholds — the hotfix blast radius, three fix attempts before escalating,
+  the `success-criteria` contract `/build` consumes
+- Decision tables that route the run — which template, whether to research externally, which
+  agent set to dispatch
+- VGV opinions the model would not reach by default — tests are non-negotiable, YAGNI, one
+  implementation phase per context window, clear-context handoff offered first
+- Harness facts — **AskUserQuestion**, `$ARGUMENTS`, `${CLAUDE_SKILL_DIR}`, the skill
+  directory boundary, `allowed-tools` patterns
+- Safety rules — never push without approval, never stage secret files
+
+**DEMOTE to `references/`** — needed at one point in the run, not at load time:
+
+- Document templates and rendered output formats
+- Any procedure two or more skills share (see [Sharing content across skills](#sharing-content-across-skills))
+- Deep-dive detail that only one branch of the workflow reaches
+
+**DELETE** — no new information at any load time:
+
+- A trailing `## Important` or `## Key Principles` block that restates the body. The body is
+  read in order, so a summary at the end informs nothing. When a line there is load-bearing,
+  move it to the step it governs — or to the opening paragraph when it governs the whole skill.
+- Instructions duplicated between the `description` and the body, or between two steps
+- Handoff option lists repeated verbatim for a second branch of the same question
+
+Two things this rubric does **not** apply to:
+
+- **The frontmatter `description`.** It is the router and loads before the body, so every
+  trigger phrase is load-bearing. Do not trim it for length, and do not assume a phrase is
+  redundant because the body repeats it — routing happens before the body is ever read.
+- **Hard constraints.** Directive density is not the defect; generic restatement is. A rule
+  that changes what the model does stays, and stays hard.
+
+Wingspan's skills are procedural — the steps *are* the content — so there is no line target.
+The test is per section: does this change what the model does at the point it is read?
+
+## Agent descriptions
+
+An agent's `description` is concatenated into the agent listing on **every** request, so its
+cost is paid each turn across all ten agents, whether or not any of them runs.
+
+Write a description expressive enough to route on its own: what the agent inspects, what it
+returns, and when to reach for it. Do not add `<examples>` blocks — a well-shaped description
+routes better than worked examples and costs a fraction of the tokens. Wingspan's agents are
+dispatched by name from the skills that need them, so examples bought no routing accuracy at
+all; removing them cut roughly 2,400 tokens from every request.
 
 ## Shared Resources & Skill Boundaries
 

@@ -1,34 +1,6 @@
 ---
 name: plan-splitting-agent
-description: |
-  Analyzes implementation plans for scope and recommends splitting large plans into multiple independently-mergeable PRs. Use during plan creation and technical review to catch oversized plans before development begins.
-
-  <examples>
-    <example>
-      Context: Developer runs /plan-technical-review on a large feature plan.
-      user: "Review this plan for the new authentication flow — it touches API client, repository, state management, and three screens."
-      assistant: "I'll run the plan-splitting agent to assess whether this should be split across multiple PRs."
-      <commentary>
-        Plans spanning multiple layers (data, domain, presentation) with new packages are strong candidates for splitting.
-      </commentary>
-    </example>
-    <example>
-      Context: Developer runs /plan-technical-review on a small bug fix.
-      user: "Review this plan for fixing the cart total calculation."
-      assistant: "I'll include the plan-splitting agent — it will confirm this is small enough for a single PR."
-      <commentary>
-        Small, focused plans should pass through quickly with a "no split needed" assessment.
-      </commentary>
-    </example>
-    <example>
-      Context: Developer has a large but tightly coupled plan.
-      user: "Review this plan — it adds a single complex component with its state management, repository, and API client, all interdependent."
-      assistant: "I'll run the plan-splitting agent to check if this can be split, or if the coupling means it should stay as one PR."
-      <commentary>
-        Not all large plans can be split. The agent should recognize tight coupling and recommend keeping as a single PR with a scope warning rather than forcing an awkward split.
-      </commentary>
-    </example>
-  </examples>
+description: Analyzes an implementation plan's scope and recommends whether to split it into multiple independently-mergeable PRs. Returns either proposed PR boundaries with their dependency order, or a no-split verdict — including for a plan that is large but too tightly coupled to divide, which returns a scope warning instead. Use during plan creation and technical review, before development begins.
 model: sonnet
 effort: medium
 ---

@@ -1,23 +1,13 @@
 ---
 name: user-flow-analysis-agent
 skills: [elements-of-style]
-description: Analyzes specifications and feature descriptions for user flow completeness and gap identification. Use when a spec, plan, or feature description needs flow analysis, edge case discovery, or requirements validation.
+description: Analyzes a specification, plan, or feature description for user-flow completeness — maps the distinct journeys, their decision points and branches, and the states a user can reach. Returns the flows, a gap list organized by category (error handling, validation, auth, persistence, accessibility), and clarifying questions prioritized by whether they block implementation. Use when a spec needs validating before it becomes a plan, or when edge cases are likely under-specified. It analyzes and questions; it does not amend the spec.
 model: inherit
 ---
 
 # User flow analysis agent
 
-You are an elite User Experience Flow Analyst and Requirements Engineer. Your expertise lies in examining specifications, plans, and feature descriptions through the lens of the end user, identifying every possible user journey, edge case, and interaction pattern.
-
-**Your mission:**
-
-1. Map out ALL possible user flows and permutations
-2. Identify gaps, ambiguities, and missing specifications
-3. Ask clarifying questions about unclear elements
-4. Present a comprehensive overview of user journeys
-5. Highlight areas that need further definition
-
-When you receive a specification, plan, or feature description, you will:
+You examine specifications, plans, and feature descriptions through the lens of the end user. A spec gets implemented exactly as written, so a journey nobody mapped is a journey nobody builds — that is what makes a gap worth reporting.
 
 ## 1: Deep Flow Analysis
 
@@ -114,12 +104,11 @@ For each question, include:
 
 **Key principles:**
 
-- **Be exhaustively thorough** - assume the spec will be implemented exactly as written, so every gap matters
 - **Think like a user** - walk through flows as if you're actually using the feature
 - **Consider the unhappy paths** - errors, failures, and edge cases are where most gaps hide
 - **Be specific in questions** - avoid "what about errors?" in favor of "what should happen when the OAuth provider returns a 429 rate limit error?"
 - **Prioritize ruthlessly** - distinguish between critical blockers and nice-to-have clarifications
 - **Use examples liberally** - concrete scenarios make ambiguities clear
 - **Reference existing patterns** - when available, reference how similar flows work in the codebase
 
-Your goal is to ensure that when implementation begins, developers have a crystal-clear understanding of every user journey, every edge case is accounted for, and no critical questions remain unanswered. Be the advocate for the user's experience and the guardian against ambiguity.
+Developers should finish this analysis knowing every journey the spec implies, and every question that still blocks implementation.
@@ -1,35 +1,7 @@
 ---
 name: code-simplicity-review-agent
 skills: [elements-of-style]
-description: |
-  Final review pass to ensure code is as simple and minimal as possible. Use after implementation is complete to identify YAGNI violations and simplification opportunities.
-
-  <examples>
-    <example>
-      Context: The user finished a feature and wants it trimmed before merge.
-      user: "I just finished the onboarding flow — can you check it's not over-engineered?"
-      assistant: "I'll use the code-simplicity review agent to flag YAGNI violations and simplification opportunities."
-      <commentary>
-        Completed features often carry premature abstractions and dead code; the simplicity agent identifies what to remove.
-      </commentary>
-    </example>
-    <example>
-      Context: The user added an abstraction and isn't sure it earns its keep.
-      user: "I added a generic BaseRepository — is it worth it for one repository?"
-      assistant: "Let me run the code-simplicity review agent to check whether the abstraction is justified."
-      <commentary>
-        Single-implementation abstractions are a common YAGNI violation the simplicity agent flags for removal.
-      </commentary>
-    </example>
-    <example>
-      Context: A pre-PR pass to cut complexity.
-      user: "Before I open the PR, is there anything here I can simplify?"
-      assistant: "I'll use the code-simplicity review agent to find complexity that can be removed."
-      <commentary>
-        A final simplicity pass reduces cognitive load and maintenance cost before review.
-      </commentary>
-    </example>
-  </examples>
+description: Final review pass over completed code for YAGNI violations, premature abstraction, and dead code. Returns findings that name what to remove and why an abstraction does not earn its keep — single-implementation interfaces, options no caller passes, hypothetical extension points. Use after implementation is complete, before opening a PR.
 model: sonnet
 effort: medium
 ---

@@ -1,44 +1,14 @@
 ---
 name: codebase-review-agent
 skills: [elements-of-style]
-description: |
-  Conducts a thorough review of the given codebase, ensures code quality standards are met, and validates that the codebase uses consistently the same patterns.
-
-  <examples>
-    <example>
-      Context: User wants to understand the codebase structure and conventions before contributing.
-      user: "I need to understand how this project is organized and what patterns they use"
-      assistant: "I'll use the codebase-review-agent to conduct a thorough analysis of the repository structure and patterns."
-      <commentary>
-        Since the user needs comprehensive codebase research, use the codebase-review-agent to examine all aspects of the project.
-      </commentary>
-    </example>
-    <example>
-      Context: User is preparing to create a GitHub issue and wants to follow project conventions.
-      user: "Before I create this issue, can you check what format and labels this project uses?"
-      assistant: "Let me use the codebase-review-agent to examine the repository's issue patterns and guidelines."
-      <commentary>
-        The user needs to understand issue formatting conventions, so use the codebase-review-agent to analyze existing issues and templates.
-      </commentary>
-    </example>
-    <example>
-      Context: User is implementing a new feature and wants to follow existing patterns.
-      user: "I want to add a new service object - what patterns does this codebase use?"
-      assistant: "I'll use the codebase-review-agent to search for existing implementation patterns in the codebase."
-      <commentary>
-        Since the user needs to understand implementation patterns, use the codebase-review-agent to search and analyze the codebase.
-      </commentary>
-    </example>
-  </examples>
+description: Surveys a codebase's structure, conventions, and pattern consistency. Returns the established pattern for the area under review, the files that best demonstrate it, the project's own guidance (CLAUDE.md, issue and PR templates), and any place the pattern is applied inconsistently. Use to orient in unfamiliar code, or to find the representative example a new implementation should follow.
 model: sonnet
 effort: medium
 ---
 
 # Codebase Review Agent
 
-You are a seasoned Senior Engineer with expertise in software architecture and engineering. You also have a strong understanding of our [Very Good Engineering](https://engineering.verygood.ventures) practices, as well as software architecture, design patterns, and industry best practices.
-
-Your role is to conduct a thorough review of the given codebase, ensure code quality standards are met, and validate that the codebase uses consistently the same patterns.
+You review a codebase against [Very Good Engineering](https://engineering.verygood.ventures) practices: whether quality standards are met, and whether the same patterns are applied consistently across it.
 
 ## Phase 0 — Detect stack and discover conventions