// Specification quality framework for planning. Defines the minimum bar for what a plan must address — alternatives, non-goals, blast radius, risk flags, and test strategy. Referenced by schema guidance fields during queue-phase note filling. Use when filling requirements or design notes for any MCP work item.
Launcher for the Ralph-style queue drain script — emits the right `node ralph-loop.mjs` invocation based on the user's filter and bounds. The actual loop runs as a Node script that spawns one `claude -p --worktree` per iteration; this skill is the configurator, not the loop. Use when a user says: drain the backlog, ralph the queue, run Ralph loop, work the queue, batch through queue items, autonomous queue worker.
Creates, views, edits, deletes, and validates note schemas for the MCP Task Orchestrator in .taskorchestrator/config.yaml — the templates that define which notes agents must fill at each workflow phase. Also manages the actor_authentication config block: set actor authentication policy, configure degraded mode, show actor_authentication config, set degradedModePolicy to reject, what's the current degraded mode policy. Use when user says: create schema, show schemas, edit schema, delete schema, validate config, what schemas exist, add a note to schema, remove note from schema, or configure gates.
SQLite migration assessment for items with the needs-migration-review trait. Evaluates schema changes, table recreation patterns, data migration strategy, and Flyway migration correctness. Invoked via skillPointer when filling migration-assessment notes.
Performance impact assessment for items with the needs-perf-review trait. Evaluates hot paths, query patterns, and measurement plans. Invoked via skillPointer when filling performance-baseline notes.
Assessment of plugin skill and hook changes needed after MCP or config changes. Evaluates skill references, hook context, config-format docs, and output style references. Invoked via skillPointer when filling plugin-impact notes.
End-to-end workflow for taking MCP work items from backlog to merged PR. Handles git branching, schema-driven planning, implementation, independent review, and PR creation. Composes spec-quality, review-quality, and schema-workflow skills into a single pipeline. Use when a user says "implement this", "work on this item", "fix these bugs", "pick up the next task", "create a PR for this", "go through the backlog", or references specific MCP item IDs for implementation.
| name | spec-quality |
| description | Specification quality framework for planning. Defines the minimum bar for what a plan must address — alternatives, non-goals, blast radius, risk flags, and test strategy. Referenced by schema guidance fields during queue-phase note filling. Use when filling requirements or design notes for any MCP work item. |
| user-invocable | false |
This skill defines the minimum thinking floor for plans and specifications. The sections below represent what every plan must address. They are not a ceiling — if the problem demands additional analysis, add it. But these areas must not be skipped.
The value of a spec is entirely in the thinking it forces before code is written. If a section doesn't change how you'd approach implementation, it isn't earning its place. Every sentence should either prevent a mistake or force a decision.
These are the required areas of analysis. Each one exists because skipping it leads to a specific, recurring class of failure.
Evaluate at least two real approaches. "Do nothing" always counts as one. For each alternative, state what it would look like and the specific trade-off that led to its rejection. If you can only think of one approach, you haven't explored the solution space — step back and look for a fundamentally different angle.
The point is not to document alternatives for posterity. It's to catch yourself before committing to an approach that has a better option sitting next to it.
Anti-pattern: strawman alternatives. "Alternative: rewrite everything from scratch. Rejected: too much work." This doesn't force any real thinking.
If the spec lists open decisions, naming alternatives, or "options under consideration," resolve every one before materializing MCP work items or dispatching implementation. A spec with unresolved choices left in it is not ready to dispatch.
Mid-implementation pivots cost 5-10× the time of a pre-dispatch user round-trip. Once an agent is in a worktree, a naming change or interface change requires unwinding partial code, retracting commits, re-spec'ing the work, and re-dispatching. Resolving the same question before dispatch is a single short conversation.
The orchestrator should pause for a user round-trip rather than dispatch with ambiguity. A short pause now is cheaper than a partial implementation later.
If a decision genuinely cannot be resolved at planning time (e.g., depends on a measurement only available post-implementation), it isn't an "open decision" — it's a deliberate two-phase approach. Document it as such, scope the first phase explicitly, and create a separate work item for the second phase. Don't leave the choice latent in the spec.
Name what someone might reasonably expect this work to include but that is deliberately excluded. If you cannot name a single non-goal, the scope is not tight enough.
Non-goals prevent scope creep during implementation. Without them, agents tend to gold-plate — adding adjacent improvements that weren't asked for and that introduce unplanned risk.
Identify every module, file, and interface affected by the change. Trace downstream consumers — if you change a repository method signature, what tools call it? If you change a domain model default, what tests assume the old value?
This analysis exists to catch "I didn't realize changing X breaks Y" before it happens.
Read references/project-concerns.md for cross-cutting constraints specific to this
codebase that frequently expand blast radius in non-obvious ways.
Call out the one or two things most likely to go wrong. These might be areas of tight coupling, migration complexity, concurrency concerns, or simply parts of the codebase you don't fully understand yet.
The purpose is to focus review attention where it matters and to make uncertainty explicit rather than hidden.
Every plan must include a concrete test strategy. This is not "add tests" — it's a specific accounting of what will be verified and how.
Required coverage areas:
For each area, name the specific scenarios you'll test. "Test edge cases" is not a strategy. "Test that circular parent references are detected and rejected with a clear error" is.
If the change modifies shared interfaces (domain models, repository contracts, tool parameters), note which existing tests may break and how you'll handle that — update them, or confirm they still pass with the new behavior.
Validate spec completeness before advancing past queue phase:
This framework sets a floor. The disciplines above are the minimum required analysis. Depending on the complexity of the work, additional analysis may be warranted — performance implications, migration strategies, API compatibility concerns, or anything else that would change the implementation approach if examined carefully.
Add whatever the problem demands. The goal is a plan that lets someone implement the change confidently, understanding not just what to build but why this approach was chosen and what to watch out for.
