refactor: convert create-tech-spec to sharded workflow with orient-first pattern #1185
Conversation
|
@CodeRabbit review |
✅ Actions performedReview triggered.
|
📝 WalkthroughWalkthroughThe create-tech-spec workflow is refactored from YAML-based configuration to markdown-based step files. The monolithic workflow.yaml and instructions.md are replaced with workflow.md and four sequential step files (understand, investigate, generate, review). A reusable tech-spec-template.md is introduced. The agent configuration references the new workflow.md format. One minor tool naming update occurs in an existing quick-dev step. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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: 0
🧹 Nitpick comments (1)
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md (1)
29-29: Clarify slug variable capture.The instruction says "extract
slugfrom frontmatter for later use" but doesn't explicitly show storing it as a variable. Consider being more explicit about capturing the slug value for use in the rename operation at line 82.Suggested clarification
**Read `{wipFile}` completely and extract `slug` from frontmatter (store as `{slug}` variable for later use).**
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
src/modules/bmm/agents/quick-flow-solo-dev.agent.yamlsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/instructions.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yamlsrc/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md
💤 Files with no reviewable changes (2)
- src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/instructions.md
- src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.yaml
🧰 Additional context used
📓 Path-based instructions (1)
**/*
⚙️ CodeRabbit configuration file
**/*: Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:<code changes>
Files:
src/modules/bmm/agents/quick-flow-solo-dev.agent.yamlsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.mdsrc/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.mdsrc/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md
🪛 LanguageTool
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md
[style] ~17-~17: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... steps. - MUST NOT optimize sequence. - MUST follow exact instructions. ## CONTEXT:...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~51-~51: Consider an alternative to strengthen your wording.
Context: ...he affected sections - Ask if there are more changes - Loop until user is satisfied b) **If...
(CHANGES_ADJUSTMENTS)
[style] ~165-~165: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...rename file to tech-spec-{slug}.md. - MUST provide clear next-step guidance and re...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md
[style] ~14-~14: Consider a different adjective to strengthen your wording.
Context: ...elta Progress: Step 1 of 4 - Next: Deep Investigation ## RULES: - MUST NOT sk...
(DEEP_PROFOUND)
[style] ~20-~20: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... steps. - MUST NOT optimize sequence. - MUST follow exact instructions. - MUST NOT l...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~21-~21: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ce. - MUST follow exact instructions. - MUST NOT look ahead to future steps. ## CON...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~93-~93: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...likely scope based on what you found? - What questions do you NOW have, informed by ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.md
[style] ~18-~18: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... steps. - MUST NOT optimize sequence. - MUST follow exact instructions. - MUST NOT g...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~19-~19: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ce. - MUST follow exact instructions. - MUST NOT generate the full spec yet (that's ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.md
[style] ~18-~18: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... steps. - MUST NOT optimize sequence. - MUST follow exact instructions. - MUST NOT i...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~19-~19: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ce. - MUST follow exact instructions. - MUST NOT implement anything - just document....
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md
[uncategorized] ~56-~56: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...Rules (NO EXCEPTIONS) - NEVER load multiple step files simultaneously - ALWAYS read ...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🔇 Additional comments (10)
src/modules/bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md (1)
82-82: Tool name update looks correct.The change from
WriteTodostoTodoWriteappears to be an intentional naming correction. The logic for creating TODOs or presenting findings as a table is appropriate.src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.md (1)
1-74: Template structure is well-designed.The tech-spec template provides a comprehensive structure with appropriate frontmatter fields and content sections. The placeholder syntax is consistent and aligns with the step files that will populate it.
src/modules/bmm/agents/quick-flow-solo-dev.agent.yaml (1)
22-22: Workflow reference updated correctly.The change from
workflow.yamltoworkflow.mdaligns with the PR's refactoring objective to use markdown-based workflow specifications.src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md (1)
139-139: Tool reference is consistent.The
TodoWritereference aligns with the updated tool naming in the quick-dev adversarial review step.src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.md (1)
1-127: Implementation plan generation step is well-structured.The step provides clear instructions for generating actionable tasks with file paths, testable acceptance criteria in Given/When/Then format, and proper state management. The status update to 'review' (not 'ready-for-dev') correctly reflects that Step 4 performs final review.
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.md (1)
1-142: Investigation step is comprehensive and well-designed.The step provides a thorough investigation process with clear handling for both brownfield and greenfield scenarios. The "Confirmed Clean Slate" pattern (lines 56-61) and the recommendation to isolate deep exploration in sub-agents (line 63) are excellent practices that prevent context overload.
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md (2)
17-26: Ready for Development standard is well-defined.The criteria are specific, actionable, and provide clear guidance for what constitutes a complete tech-spec. This standard aligns well with the step-by-step process defined in the workflow.
10-10: No issue found. The file path on line 10 correctly referencesquick-dev/workflow.md, which exists in the repository.Likely an incorrect or invalid review comment.
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md (2)
32-64: WIP resume logic is well-designed.The check for work-in-progress is performed first (Section 0) before any other action, and the jump logic correctly routes to the appropriate step based on the
stepsCompletedarray. This prevents users from losing work and enables seamless workflow resumption.
73-96: Orient-first pattern is a significant improvement.The Quick Orient Scan (Section 2) executed before asking questions (Section 3) is the key innovation mentioned in the PR objectives. This enables the agent to ask informed, context-aware questions rather than generic ones, which should significantly improve the quality of the tech-spec. The 30-second time guidance is a pragmatic constraint to prevent scope creep at this stage.
cecil-the-coder
left a comment
cecil-the-coder
left a comment
There was a problem hiding this comment.
Looks good to me!
There was a problem hiding this comment.
Pull request overview
This PR refactors the create-tech-spec workflow from a monolithic instruction file to a sharded step-file architecture, enhancing workflow discipline and state management. The key improvements include converting the single instructions.md to four distinct step files, implementing a WIP file pattern for session persistence, adding an "orient-first" pattern in Step 1 that performs quick code scans before asking informed questions, removing the brownfield/greenfield conditional branching in favor of a unified flow, and adding an adversarial review option to the final step menu.
Key Changes:
- Migrates workflow configuration from YAML format to Markdown format with embedded frontmatter
- Replaces monolithic instructions.md with four sequential step files (understand → investigate → generate → review)
- Implements WIP file pattern with
stepsCompletedtracking for workflow resumption across sessions
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| step-05-adversarial-review.md | Corrects tool name from "WriteTodos" to "TodoWrite" and capitalizes "TODO" consistently |
| workflow.yaml | Removes legacy YAML workflow configuration file |
| workflow.md | Introduces new Markdown-based workflow configuration with step-file architecture rules and initialization sequence |
| tech-spec-template.md | Adds structured template for tech-spec documents with frontmatter for state tracking |
| step-04-review.md | Creates final review and finalization step with adversarial review option in the completion menu |
| step-03-generate.md | Creates implementation plan generation step that produces actionable tasks and acceptance criteria |
| step-02-investigate.md | Creates deep code investigation step that maps technical constraints and anchor points |
| step-01-understand.md | Creates initial understanding step with WIP resumption logic and orient-first code scanning |
| instructions.md | Removes legacy monolithic instruction file |
| quick-flow-solo-dev.agent.yaml | Updates workflow path reference from workflow.yaml to workflow.md |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md
Outdated
Show resolved
Hide resolved
src/modules/bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md
Outdated
Show resolved
Hide resolved
…l code investigation section
…nt' in step-02-investigate.md context.
…ps/step-04-review.md Co-authored-by: Copilot <[email protected]>
…ps/step-01-understand.md Co-authored-by: Copilot <[email protected]>
alexeyv
force-pushed
the
feature/shard-create-tech-spec
branch
from
45686be to
a2e413f
Compare
|
one minor issue with discovery path, but will fix with a follow up PR as there are more phase 4 discovery updates also needed before next release |
4 participants
Summary
Test plan