Enhance proposal guidelines in slash-command-templates.ts #306
Conversation
- Added instructions to avoid writing code during the proposal stage and focus on creating design documents. - Emphasized the design phase by including a reminder not to implement code until the apply stage. - Updated validation steps to clarify the importance of confirming project conventions before proceeding with tasks.
WalkthroughAdds explicit design-only guardrail forbidding writing implementation code during the proposal stage, extends proposal references to instruct exploring the codebase for alignment, and inserts a minor formatting blank line; changes are confined to a single slash-command template file. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant ProposalCmd as "proposalSteps / guardrails"
note right of ProposalCmd `#FFF3E0`: New guardrail — design-only, no implementation code
User->>ProposalCmd: invoke /proposal
ProposalCmd-->>User: step-by-step instructions
ProposalCmd-->>User: "Design-only: do not write implementation code in this stage."
ProposalCmd->>User: "Check codebase to align proposals with current implementation."
sequenceDiagram
participant User
participant ApplyCmd as "applySteps (template)"
participant ProjectDoc as "openspec/project.md"
participant ProposalFiles as "proposal files"
note right of ApplyCmd `#E8F5E9`: Updated flow — read project conventions first
User->>ApplyCmd: invoke /apply
ApplyCmd->>ProjectDoc: read project conventions
ProjectDoc-->>ApplyCmd: conventions/context
ApplyCmd->>ProposalFiles: open review artifacts
ProposalFiles-->>ApplyCmd: proposal content
ApplyCmd-->>User: guidance + review checklist
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20–30 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🔇 Additional comments (4)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
src/core/templates/slash-command-templates.ts(3 hunks)
🔇 Additional comments (2)
src/core/templates/slash-command-templates.ts (2)
8-9: Excellent addition to enforce design-only work in proposals.The explicit guardrail clearly separates design from implementation and lists the expected deliverables for the proposal stage. This should help prevent premature code generation, especially with moderate-capability models.
28-28: No changes needed—code improvement verified.The change at line 28 is well-founded:
openspec/project.mdexists, is automatically created during init, recreated if deleted in extend mode, and referenced consistently across templates, tests, and documentation. Prioritizing project conventions before reading proposal files is a sound structural improvement.
…hat no implementation code should be written during the design phase.
TabishB
left a comment
TabishB
left a comment
There was a problem hiding this comment.
A few questions below :)
| - Refer to \`openspec/AGENTS.md\` (located inside the \`openspec/\` directory—run \`ls openspec\` or \`openspec update\` if you don't see it) if you need additional OpenSpec conventions or clarifications.`; | ||
|
|
||
| const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.`; | ||
| const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files. |
There was a problem hiding this comment.
@jax-max How has this updated instruction been working for you? Do you feel like this has COMPLETELY stopped the agent from writing code?
Will try it out, but keen to hear your experience first?
There was a problem hiding this comment.
Mainly asking to just get a sense of whether this actually works, i'm ok with the change itself, because I agree that it's a problem.
There was a problem hiding this comment.
@TabishB Hi there! Our team (not only me) has noticed that code automatically starts being written during the proposal phase. We’ve checked the system prompt of the tool being used and found no issues—it’s a rather odd problem.
Adding a clarifying note here might theoretically help a bit, but the LLM will probably still not behave as intended, haha.
We’re wondering if you’ve encountered this issue before?
| 5. Draft spec deltas in \`changes/<id>/specs/<capability>/spec.md\` (one folder per capability) using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement and cross-reference related capabilities when relevant. | ||
| 6. Draft \`tasks.md\` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work. | ||
| 7. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal.`; | ||
| 7. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal. |
There was a problem hiding this comment.
Interesting you decided to add this here as well. Any particular reason?
There was a problem hiding this comment.
Just to clarify again—our model’s compliance is really subpar. Feel free to delete this if you find it redundant.
| const applySteps = `**Steps** | ||
| Track these steps as TODOs and complete them one by one. | ||
| 1. Read \`changes/<id>/proposal.md\`, \`design.md\` (if present), and \`tasks.md\` to confirm scope and acceptance criteria. | ||
| 1. Read \`openspec/project.md\` to understand project conventions, then read \`changes/<id>/proposal.md\`, \`design.md\` (if present), and \`tasks.md\` to confirm scope and acceptance criteria. |
There was a problem hiding this comment.
Hm, I'm not too sure if this makes sense. The idea is using the project context to create the plan and then using the plan to implement.
project context -> plan -> implement
If you've used the project context to create the plan then you most likely don't need to read the context again during the implementation stage. The plan should already be created with the project context in mind.
So IMO, it's a bit redundant here to read the context again and possibly using more tokens than we need.
If you've had a different experience here, let me know!
There was a problem hiding this comment.
@TabishB Greetings! It may be that the limited number of chapters in the OpenSpec document template leads to significant information loss during the project context → plan phase, which in turn affects the code accuracy in the plan → implement phase.
From our practice, a simple fix is to revisit and re-read the project context during the plan → implement phase. A more elegant solution could be supporting custom plan templates : #307
I'd love to hear your thoughts. Looking forward to your reply!
- Removed redundant instruction in proposal steps to streamline the process. - Clarified the initial reading order for apply steps by omitting the project conventions document, focusing on the proposal and design documents instead.
…pec into feat/ImproveGenCodeQuality # Conflicts: # src/core/templates/slash-command-templates.ts
…#306) * Enhance proposal guidelines in slash-command-templates.ts - Added instructions to avoid writing code during the proposal stage and focus on creating design documents. - Emphasized the design phase by including a reminder not to implement code until the apply stage. - Updated validation steps to clarify the importance of confirming project conventions before proceeding with tasks. * Update proposal guidelines in slash-command-templates.ts to clarify that no implementation code should be written during the design phase. * Refine proposal and apply steps in slash-command-templates.ts - Removed redundant instruction in proposal steps to streamline the process. - Clarified the initial reading order for apply steps by omitting the project conventions document, focusing on the proposal and design documents instead.
…#306) * Enhance proposal guidelines in slash-command-templates.ts - Added instructions to avoid writing code during the proposal stage and focus on creating design documents. - Emphasized the design phase by including a reminder not to implement code until the apply stage. - Updated validation steps to clarify the importance of confirming project conventions before proceeding with tasks. * Update proposal guidelines in slash-command-templates.ts to clarify that no implementation code should be written during the design phase. * Refine proposal and apply steps in slash-command-templates.ts - Removed redundant instruction in proposal steps to streamline the process. - Clarified the initial reading order for apply steps by omitting the project conventions document, focusing on the proposal and design documents instead.
2 participants
Fix Slash Command Instructions to Prevent Code Writing in Proposal Phase
Problem
I encountered two issues when using OpenSpec:
Code writing during proposal phase: Code writing started during the
/openspec-proposalphase, while the expectation was to only draft design documents (proposal.md, tasks.md, design.md, and spec deltas).Missing project.md reference in apply phase: During the
/openspec-applyphase, the LLM overlooked the content inproject.md(I'm using the GLM-4.6 model, which has moderate capabilities). This could lead to implementations that don't follow project conventions.Solution
This PR optimizes the prompt content in slash command templates to address both issues:
Changes Made
Added explicit guardrail in proposal phase: Added instructions to
proposalGuardrailsto avoid writing any code during the proposal stage and focus on creating design documents only. Implementation should happen in the apply stage after approval.Emphasized design phase: Added a reminder in
proposalStepsto clarify that this is a design phase and no implementation code should be written.Updated apply phase validation: Modified
applyStepsto require readingopenspec/project.mdfirst to understand project conventions before proceeding with implementation tasks. This ensures the LLM follows project conventions even with moderate-capability models.Technical Details
src/core/templates/slash-command-templates.ts:proposalGuardrailswith explicit code-writing prohibitionproposalStepsapplyStepsto includeproject.mdreading as the first stepImpact
These changes ensure that:
project.mdduring the apply phase to follow project conventionsSummary by CodeRabbit