From devco-agent-skills
Surface ambiguity, missing requirements, hidden assumptions BEFORE planning. Fires after triage for standard (vague request) or high-stakes (always). Updates CONTEXT.md vocabulary. Produces agreed-requirements artifact feeding Plan gate.
How this skill is triggered — by the user, by Claude, or both
Slash command
/devco-agent-skills:alignThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> "No one knows exactly what they want." — Pragmatic Programmer
"No one knows exactly what they want." — Pragmatic Programmer
Plan before align = plan on wrong prompt. Build on wrong plan = waste.
Always:
Vague indicators:
Skip:
## My understanding
You want to <restated task> because <inferred reason>.
Specifically:
- <requirement 1>
- <requirement 2>
- <requirement 3>
Is this correct?
User confirms or corrects.
## Assumptions I'm making
1. <e.g., "Existing OrderService modified, not new service">
2. <e.g., "Postgres remains the database">
3. <e.g., "No breaking change to public API">
4. <e.g., "Existing test suite covers affected paths">
Any wrong?
Pick 3-5 most relevant per task:
Behavior gaps: error types, latency targets, invalid input, rollback, concurrency
Data gaps: validation rules, retention, migration, backup/recovery
Integration gaps: upstream/downstream consumers, monitoring, auth rules
Operational gaps: deployment strategy, observability, feature flags, docs
Detail: references/grill-questions.md.
Capture domain terms during grilling: nouns, process names, acronyms, custom verbs. Add to CONTEXT.md. Reuse cross-session.
Output template → .claude/memory/align-artifacts/<YYYY-MM-DD>-<task-name>.md:
# Alignment: <Task name>
**Date:** YYYY-MM-DD
**Lane:** Standard | High-stakes
## Agreed requirements
1. <Specific requirement 1>
2. <Specific requirement 2>
## Assumptions (confirmed by user)
1. <Confirmed assumption 1>
## Out of scope
1. <Explicit non-goal 1>
## New vocabulary added to CONTEXT.md
- <Term 1>: <definition>
## Open questions for Brainstorm / Plan
1. <Question affecting solution choice>
Don't: all questions at once, philosophical questions, skip restate-and-confirm, forget CONTEXT.md update.
Do: 3-5 focused questions per round, concrete examples, acknowledge clear parts, persist to CONTEXT.md, offer to proceed early.
| Downstream | Reads |
|---|---|
| Brainstorm | Agreed requirements (problem framing) |
| Plan | Same (decomposition input) |
| Spec | Same (scenario coverage) |
| Pre-flight 1 (brainstorm-prep) | Open questions section |
session-init.sh when TRIAGE_LANE=high-stakes or vague request/align.claude/memory/align-artifacts/references/grill-questions.md — full question library, 5 patternsskills/triage/SKILL.md — runs before Alignskills/brainstorm/SKILL.md — consumes Align outputcommands/align.md — entry pointtemplates/CONTEXT_TEMPLATE.md — vocabulary destinationnpx claudepluginhub taipt1504/agent-skills --plugin devco-agent-skillsGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.