| name | clarify-requirements |
| description | Analyze requirements for gaps, ambiguities, and unstated assumptions before implementing. This is "negative space analysis" — finding what the spec doesn't say that it should. Use this skill when you receive a task, ticket, user story, or feature request and need to identify specifics before implementing. Triggers on phrases like "build this feature", "implement this", "I want to...", or any time you're handed a task description that you need to start working from. The most expensive bugs come from building the wrong thing, not from building the right thing incorrectly — this skill prevents the former.
|
Clarify Requirements
Senior engineers read specifications differently than junior engineers. A junior reads what's
there. A senior reads what's not there. They notice the missing error states, the unspecified
edge cases, the assumptions that seem obvious today but will cause arguments next month.
This isn't pessimism — it's pattern recognition. After seeing enough features launch with
gaps, you develop an instinct for the questions nobody thought to ask. This skill makes that
instinct explicit and systematic.
Step 0: Load Existing Context
Before analyzing gaps in the requirements, understand what already exists. Building
something that duplicates or conflicts with an existing capability is worse than missing
an edge case.
If gjalla is available, query these tools first:
get_context(scope="capabilities") — load the existing feature catalog. Check whether
the requested feature overlaps with, extends, or conflicts with anything already active
or proposed. If a "proposed" capability matches the request, the team may already
have opinions about how it should work.get_context(scope="data_flows") — trace how data currently moves through the system
in the area you're about to change. This surfaces integration points the spec might
not mention.get_context(scope="rules") — check for invariants or principles that constrain how
this type of feature should be built (e.g., "all user-facing features must support
multi-tenancy").
If gjalla is not available, scan for existing specs, feature docs, or planning
documents in the repo and Notion before starting the analysis.
The Negative Space Framework
For any set of requirements, work through these dimensions. Each one surfaces a different
class of gap.
1. Failure Modes
For every described behavior, ask: "What happens when this doesn't work?"
- The spec says "send a notification when the order ships." What happens if the notification
system is down? Does the shipment proceed? Does it retry? Is there a fallback?
- The spec says "validate the user's email." What happens when validation fails? What message
does the user see? Can they retry? Is there a rate limit?
- The spec says "sync data from the external API." What happens when the API is slow?
When it returns partial data? When it returns data in an unexpected format?
The rule: every verb in the spec ("send", "validate", "sync", "create", "update", "delete")
has a failure mode that probably isn't specified. Find them.
2. Boundary Conditions
For every value or quantity, ask: "What happens at the extremes?"
- The spec says "users can add items to their cart." How many items? Is there a limit?
What happens at that limit?
- The spec says "display the user's name." How long can the name be? What about special
characters, unicode, RTL text? What about users with no name set?
- The spec says "process transactions." What's the maximum amount? The minimum? What
about zero? Negative values? Multiple currencies?
The rule: every noun in the spec ("items", "name", "transactions") has boundary conditions
that probably aren't specified. Find them.
3. State Transitions
For every entity that changes state, map the complete lifecycle:
- What states can it be in? (Not just the ones mentioned in the spec.)
- What transitions are valid? (And critically, which are invalid?)
- What happens if someone tries an invalid transition?
- Can an entity go backward in its lifecycle?
- What about concurrent state changes — can two people try to transition the same entity
at the same time?
The rule: state machines have more states than the spec describes. The spec describes the
happy path. Find the other states.
4. Timing and Ordering
For any process with multiple steps, ask:
- Does the order matter? What happens if steps occur out of order?
- Can steps happen concurrently? What if two users trigger the same flow simultaneously?
- Are there time-sensitive aspects? Expiration, timeouts, rate limits?
- What happens between steps — is the intermediate state visible to other parts of the system?
- What about time zones, daylight saving time, leap years, month boundaries?
5. Actors and Permissions
For every action described, ask:
- Who can do this? Just the owner? Admins? Anyone?
- What about different user tiers or roles?
- Can this action be undone? By whom?
- What audit trail is needed?
- What about automated actors — background jobs, webhooks, API integrations?
6. Backwards Compatibility
For any change to existing behavior, ask:
- What currently works that might break?
- Are there existing API consumers depending on the current behavior?
- Is there cached data that assumes the old format?
- Are there scheduled jobs running against the old logic?
- What about mobile apps that can't be force-updated?
- Do database migrations need to be reversible?
7. Observability and Operability
Requirements almost never specify these, but you need answers:
- How will we know this is working correctly in production?
- How will we know when it breaks?
- How will we debug issues?
- What metrics, logs, or alerts do we need?
- Who gets paged when this breaks at 3am?
Surfacing Questions Effectively
Once you've identified the gaps, present them in a way that makes decisions easy rather
than overwhelming. Group questions by impact:
Critical (blocks implementation)
Questions where the answer fundamentally changes the architecture or approach. You can't
start coding without these answers.
Example: "The spec says 'sync data in real-time.' Does that mean sub-second latency
(requires WebSocket/streaming) or within-a-few-minutes (a polling job is fine)? These
are entirely different architectures."
Important (need answers before shipping)
Questions where a reasonable default exists, but the product/business stakeholders should
confirm the choice.
Example: "The spec doesn't say what happens when a user tries to add a 101st item to their
cart. I'll default to showing an error message, but should we auto-remove the oldest item,
or expand the limit for premium users?"
Minor (can decide during implementation)
Questions where any reasonable answer is fine and can be adjusted later without rework.
Example: "The spec doesn't specify the sort order for search results. I'll default to
relevance. Easy to change later."
Output
Produce a requirements clarification document:
## Requirements Clarification: [Feature/Ticket Name]
### Critical Questions (blocks implementation)
1. [Question] — [why this matters]
2. [Question] — [why this matters]
### Important Questions (need answers before shipping)
1. [Question] — [recommended default if not answered]
2. [Question] — [recommended default if not answered]
### Minor Questions (will decide during implementation)
1. [Question] — [proposed default]
2. [Question] — [proposed default]
### Assumptions
[List of assumptions you're making based on context, existing patterns, or common sense.
These are things you believe to be true but that aren't explicitly stated.]
Share this with the user or stakeholders before starting implementation. The 20 minutes
spent identifying gaps saves days of rework.
Cross-System Context
If the requirement touches areas documented across multiple systems, reference all of them:
- Existing capabilities: [from gjalla
get_context(scope="capabilities") — what already exists]
- Architecture constraints: [from gjalla
get_context(scope="rules") — what rules apply]
- Data flow impacts: [from gjalla
get_context(scope="data_flows") — integration points affected]
- Related discussions: [from Slack — relevant threads where this was discussed]
- Existing specs: [from Notion — related design docs or brainstorms]
This cross-system view ensures the requirements clarification reflects the full context,
not just what's in the ticket.
