| name | openspec-nudge |
| description | Detect complex or bulk tasks and nudge toward OpenSpec workflow. Use proactively when user asks to do something across multiple repos, migrate or refactor a large surface area, create many issues or PRs at once, do bulk operations on 5+ entities, implement a multi-step feature touching several files or systems, or when single-shotting has already produced corrections. Trigger phrases include "for each repo", "across all", "migrate", "bulk", "batch", "rollout", "for every", "update all repos". |
OpenSpec Nudge
You have detected a task that is likely too complex or broad for a single-shot approach. Before proceeding, help the user make a deliberate choice about their workflow.
Detection Criteria
This skill triggers when the user's request matches ANY of:
- Multi-entity scope — the task targets 5+ repos, files, services, issues, or PRs
- Cross-repo intent — the task mentions "across repos", "for each repo", "all repositories", "every service"
- Migration/refactoring — large-surface changes like "migrate from X to Y", "upgrade all", "refactor across"
- Bulk creation — "create issues for each", "open PRs for all", "add file to every repo"
- Repeated corrections — the user has already corrected you 2+ times on the current task, suggesting the task is more complex than initially assumed
What To Do
Step 1: Acknowledge the complexity
Briefly explain WHY this task benefits from structured planning:
- Multiple entities = higher risk of data accuracy errors (FM1)
- Cross-repo = needs constraint extraction and dry-run verification
- Bulk operations = need the 4-phase protocol to avoid partial failures
Step 2: Present options
Use the Question tool to ask the user:
This looks like a complex task that touches multiple [repos/entities/systems].
Based on analysis of past sessions, these tasks have a higher correction rate
when single-shotted. Would you like to:
Options:
- Explore first — Use
/opsx-explore to think through the approach, investigate unknowns, and clarify requirements before committing to a plan
- Propose a change — Use
/opsx-propose to generate a complete proposal with design decisions, specs, and implementation tasks
- Continue as-is — Proceed with the current approach (you know what you're doing)
Step 3: Follow the user's choice
- If Explore: Invoke the openspec-explore skill
- If Propose: Invoke the openspec-propose skill
- If Continue: Proceed normally, but consider loading the
bulk-ops or self-audit skill if the task involves bulk operations or aggregation
Important
- NEVER block the user — always offer "continue as-is" as an option
- NEVER be preachy — one short sentence explaining why, then present options
- If the user has already started an OpenSpec change for this task, don't nudge again
- If the user explicitly says "just do it" or "skip planning", respect that immediately
