fix: prevent implementation during explore mode #515
Conversation
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe PR enhances skill and command templates in Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review CompleteYour review story is ready! Comment !reviewfast on this PR to re-generate the story. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @.agent/skills/openspec-explore/SKILL.md:
- Around line 28-68: Replace the bolded section titles ("Explore the problem
space", "Investigate the codebase", "Compare options", "Visualize", "Surface
risks and unknowns") with proper Markdown headings (e.g., prefix with `#/`## as
appropriate) in SKILL.md to satisfy markdownlint MD036 and improve document
structure; ensure the heading level is consistent across the file, update the
following content blocks to be under each new heading, and keep the ASCII
diagram and list items intact beneath the "Visualize" heading.
- Around line 47-268: The fenced code blocks in the SKILL.md examples (the ASCII
diagram block and other example blocks) lack language identifiers and trigger
markdownlint MD040; update every triple-backtick fence in the file (e.g., the
large ASCII diagram block and the "Check for context" / "When no change exists"
example blocks) to include an appropriate language tag such as text or bash (use
bash for command examples like "openspec list --json", text for
diagrams/snippets) so each fence becomes ```text or ```bash to satisfy the
linter and improve readability.
🧹 Nitpick comments (1)
.agent/skills/openspec-explore/SKILL.md (1)
71-125: Referenceopenspec/AGENTS.mdwhen capturing artifacts.Since explore can surface proposals/specs, add a brief reminder to consult
openspec/AGENTS.mdfor artifact format/conventions before capture. Based on learnings, ...♻️ Suggested addition
## OpenSpec Awareness You have full context of the OpenSpec system. Use it naturally, don't force it. +When capturing proposals/specs, consult `openspec/AGENTS.md` for required formats and conventions.
| **Explore the problem space** | ||
| - Ask clarifying questions that emerge from what they said | ||
| - Challenge assumptions | ||
| - Reframe the problem | ||
| - Find analogies | ||
|
|
||
| **Investigate the codebase** | ||
| - Map existing architecture relevant to the discussion | ||
| - Find integration points | ||
| - Identify patterns already in use | ||
| - Surface hidden complexity | ||
|
|
||
| **Compare options** | ||
| - Brainstorm multiple approaches | ||
| - Build comparison tables | ||
| - Sketch tradeoffs | ||
| - Recommend a path (if asked) | ||
|
|
||
| **Visualize** | ||
| ``` | ||
| ┌─────────────────────────────────────────┐ | ||
| │ Use ASCII diagrams liberally │ | ||
| ├─────────────────────────────────────────┤ | ||
| │ │ | ||
| │ ┌────────┐ ┌────────┐ │ | ||
| │ │ State │────────▶│ State │ │ | ||
| │ │ A │ │ B │ │ | ||
| │ └────────┘ └────────┘ │ | ||
| │ │ | ||
| │ System diagrams, state machines, │ | ||
| │ data flows, architecture sketches, │ | ||
| │ dependency graphs, comparison tables │ | ||
| │ │ | ||
| └─────────────────────────────────────────┘ | ||
| ``` | ||
|
|
||
| **Surface risks and unknowns** | ||
| - Identify what could go wrong | ||
| - Find gaps in understanding | ||
| - Suggest spikes or investigations | ||
|
|
There was a problem hiding this comment.
Use headings instead of emphasized lines.
Markdownlint flags MD036 here; converting the bold “Explore the problem space / Investigate the codebase / Compare options / Visualize / Surface risks and unknowns” lines to headings will fix lint and improve structure.
🔧 Suggested structure tweak
-**Explore the problem space**
+### Explore the problem space
...
-**Investigate the codebase**
+### Investigate the codebase
...
-**Compare options**
+### Compare options
...
-**Visualize**
+### Visualize
...
-**Surface risks and unknowns**
+### Surface risks and unknowns🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
28-28: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
34-34: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
40-40: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
46-46: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
47-47: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
64-64: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🤖 Prompt for AI Agents
In @.agent/skills/openspec-explore/SKILL.md around lines 28 - 68, Replace the
bolded section titles ("Explore the problem space", "Investigate the codebase",
"Compare options", "Visualize", "Surface risks and unknowns") with proper
Markdown headings (e.g., prefix with `#/`## as appropriate) in SKILL.md to satisfy
markdownlint MD036 and improve document structure; ensure the heading level is
consistent across the file, update the following content blocks to be under each
new heading, and keep the ASCII diagram and list items intact beneath the
"Visualize" heading.
| ``` | ||
| ┌─────────────────────────────────────────┐ | ||
| │ Use ASCII diagrams liberally │ | ||
| ├─────────────────────────────────────────┤ | ||
| │ │ | ||
| │ ┌────────┐ ┌────────┐ │ | ||
| │ │ State │────────▶│ State │ │ | ||
| │ │ A │ │ B │ │ | ||
| │ └────────┘ └────────┘ │ | ||
| │ │ | ||
| │ System diagrams, state machines, │ | ||
| │ data flows, architecture sketches, │ | ||
| │ dependency graphs, comparison tables │ | ||
| │ │ | ||
| └─────────────────────────────────────────┘ | ||
| ``` | ||
|
|
||
| **Surface risks and unknowns** | ||
| - Identify what could go wrong | ||
| - Find gaps in understanding | ||
| - Suggest spikes or investigations | ||
|
|
||
| --- | ||
|
|
||
| ## OpenSpec Awareness | ||
|
|
||
| You have full context of the OpenSpec system. Use it naturally, don't force it. | ||
|
|
||
| ### Check for context | ||
|
|
||
| At the start, quickly check what exists: | ||
| ```bash | ||
| openspec list --json | ||
| ``` | ||
|
|
||
| This tells you: | ||
| - If there are active changes | ||
| - Their names, schemas, and status | ||
| - What the user might be working on | ||
|
|
||
| ### When no change exists | ||
|
|
||
| Think freely. When insights crystallize, you might offer: | ||
|
|
||
| - "This feels solid enough to start a change. Want me to create one?" | ||
| → Can transition to `/opsx:new` or `/opsx:ff` | ||
| - Or keep exploring - no pressure to formalize | ||
|
|
||
| ### When a change exists | ||
|
|
||
| If the user mentions a change or you detect one is relevant: | ||
|
|
||
| 1. **Read existing artifacts for context** | ||
| - `openspec/changes/<name>/proposal.md` | ||
| - `openspec/changes/<name>/design.md` | ||
| - `openspec/changes/<name>/tasks.md` | ||
| - etc. | ||
|
|
||
| 2. **Reference them naturally in conversation** | ||
| - "Your design mentions using Redis, but we just realized SQLite fits better..." | ||
| - "The proposal scopes this to premium users, but we're now thinking everyone..." | ||
|
|
||
| 3. **Offer to capture when decisions are made** | ||
|
|
||
| | Insight Type | Where to Capture | | ||
| |--------------|------------------| | ||
| | New requirement discovered | `specs/<capability>/spec.md` | | ||
| | Requirement changed | `specs/<capability>/spec.md` | | ||
| | Design decision made | `design.md` | | ||
| | Scope changed | `proposal.md` | | ||
| | New work identified | `tasks.md` | | ||
| | Assumption invalidated | Relevant artifact | | ||
|
|
||
| Example offers: | ||
| - "That's a design decision. Capture it in design.md?" | ||
| - "This is a new requirement. Add it to specs?" | ||
| - "This changes scope. Update the proposal?" | ||
|
|
||
| 4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture. | ||
|
|
||
| --- | ||
|
|
||
| ## What You Don't Have To Do | ||
|
|
||
| - Follow a script | ||
| - Ask the same questions every time | ||
| - Produce a specific artifact | ||
| - Reach a conclusion | ||
| - Stay on topic if a tangent is valuable | ||
| - Be brief (this is thinking time) | ||
|
|
||
| --- | ||
|
|
||
| ## Handling Different Entry Points | ||
|
|
||
| **User brings a vague idea:** | ||
| ``` | ||
| User: I'm thinking about adding real-time collaboration | ||
|
|
||
| You: Real-time collab is a big space. Let me think about this... | ||
|
|
||
| COLLABORATION SPECTRUM | ||
| ════════════════════════════════════════════ | ||
|
|
||
| Awareness Coordination Sync | ||
| │ │ │ | ||
| ▼ ▼ ▼ | ||
| ┌────────┐ ┌────────┐ ┌────────┐ | ||
| │Presence│ │Cursors │ │ CRDT │ | ||
| │ "3 │ │ Multi │ │Conflict│ | ||
| │online" │ │ select │ │ free │ | ||
| └────────┘ └────────┘ └────────┘ | ||
| │ │ │ | ||
| trivial moderate complex | ||
|
|
||
| Where's your head at? | ||
| ``` | ||
|
|
||
| **User brings a specific problem:** | ||
| ``` | ||
| User: The auth system is a mess | ||
|
|
||
| You: [reads codebase] | ||
|
|
||
| ┌─────────────────────────────────────────────┐ | ||
| │ CURRENT AUTH FLOW │ | ||
| └─────────────────────────────────────────────┘ | ||
| │ | ||
| ┌─────────────┼─────────────┐ | ||
| ▼ ▼ ▼ | ||
| ┌─────────┐ ┌─────────┐ ┌─────────┐ | ||
| │ Google │ │ GitHub │ │ Email │ | ||
| │ OAuth │ │ OAuth │ │ Magic │ | ||
| └────┬────┘ └────┬────┘ └────┬────┘ | ||
| │ │ │ | ||
| └─────────────┼─────────────┘ | ||
| ▼ | ||
| ┌───────────┐ | ||
| │ Session │ | ||
| └─────┬─────┘ | ||
| │ | ||
| ▼ | ||
| ┌───────────┐ | ||
| │ Perms │ | ||
| └───────────┘ | ||
|
|
||
| I see three tangles. Which one's burning? | ||
| ``` | ||
|
|
||
| **User is stuck mid-implementation:** | ||
| ``` | ||
| User: /opsx:explore add-auth-system | ||
| The OAuth integration is more complex than expected | ||
|
|
||
| You: [reads change artifacts] | ||
|
|
||
| You're on task 4: "Implement OAuth flow" | ||
|
|
||
| Let me trace what's involved... | ||
|
|
||
| [draws diagram, explores options, suggests paths] | ||
|
|
||
| Want to update the design to reflect this? | ||
| Or add a spike task to investigate? | ||
| ``` | ||
|
|
||
| **User wants to compare options:** | ||
| ``` | ||
| User: Should we use Postgres or SQLite? | ||
|
|
||
| You: Generic answer is boring. What's the context? | ||
|
|
||
| User: A CLI tool that tracks local dev environments | ||
|
|
||
| You: That changes everything. | ||
|
|
||
| ┌─────────────────────────────────────────────────┐ | ||
| │ CLI TOOL DATA STORAGE │ | ||
| └─────────────────────────────────────────────────┘ | ||
|
|
||
| Key constraints: | ||
| • No daemon running | ||
| • Must work offline | ||
| • Single user | ||
|
|
||
| SQLite Postgres | ||
| Deployment embedded ✓ needs server ✗ | ||
| Offline yes ✓ no ✗ | ||
| Single file yes ✓ no ✗ | ||
|
|
||
| SQLite. Not even close. | ||
|
|
||
| Unless... is there a sync component? | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## Ending Discovery | ||
|
|
||
| There's no required ending. Discovery might: | ||
|
|
||
| - **Flow into action**: "Ready to start? /opsx:new or /opsx:ff" | ||
| - **Result in artifact updates**: "Updated design.md with these decisions" | ||
| - **Just provide clarity**: User has what they need, moves on | ||
| - **Continue later**: "We can pick this up anytime" | ||
|
|
||
| When it feels like things are crystallizing, you might summarize: | ||
|
|
||
| ``` | ||
| ## What We Figured Out | ||
|
|
||
| **The problem**: [crystallized understanding] | ||
|
|
||
| **The approach**: [if one emerged] | ||
|
|
||
| **Open questions**: [if any remain] | ||
|
|
||
| **Next steps** (if ready): | ||
| - Create a change: /opsx:new <name> | ||
| - Fast-forward to tasks: /opsx:ff <name> | ||
| - Keep exploring: just keep talking | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks.
Markdownlint MD040 is triggered across the example fences; add text (or bash where applicable) to satisfy lint and improve readability.
🔧 Example fix
-```
+```text
...
-```
+```Repeat for the other example blocks.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
47-47: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
64-64: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
143-143: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
166-166: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
197-197: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
214-214: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
255-255: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @.agent/skills/openspec-explore/SKILL.md around lines 47 - 268, The fenced
code blocks in the SKILL.md examples (the ASCII diagram block and other example
blocks) lack language identifiers and trigger markdownlint MD040; update every
triple-backtick fence in the file (e.g., the large ASCII diagram block and the
"Check for context" / "When no change exists" example blocks) to include an
appropriate language tag such as text or bash (use bash for command examples
like "openspec list --json", text for diagrams/snippets) so each fence becomes
```text or ```bash to satisfy the linter and improve readability.
Add explicit instructions to both the explore skill and slash command: - Add IMPORTANT notice clarifying explore is for thinking, not implementing - Add "Open threads, not interrogations" stance for user-driven exploration - Add "Don't implement" guardrail to both templates Creating OpenSpec artifacts is still allowed since that captures thinking.
TabishB
force-pushed
the
improve-explore-no-implementation
branch
from
77cafeb to
9d9f626
Compare
Summary
Test plan
/opsx:exploreand verify the agent follows the new instructions🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.