ace-idea 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. checksums.yaml +7 -0
  2. data/.ace-defaults/idea/config.yml +21 -0
  3. data/.ace-defaults/nav/protocols/wfi-sources/ace-idea.yml +19 -0
  4. data/CHANGELOG.md +387 -0
  5. data/README.md +42 -0
  6. data/Rakefile +13 -0
  7. data/docs/demo/ace-idea-getting-started.gif +0 -0
  8. data/docs/demo/ace-idea-getting-started.tape.yml +44 -0
  9. data/docs/demo/fixtures/README.md +3 -0
  10. data/docs/demo/fixtures/sample.txt +1 -0
  11. data/docs/getting-started.md +102 -0
  12. data/docs/handbook.md +39 -0
  13. data/docs/usage.md +320 -0
  14. data/exe/ace-idea +22 -0
  15. data/handbook/skills/as-idea-capture/SKILL.md +25 -0
  16. data/handbook/skills/as-idea-capture-features/SKILL.md +26 -0
  17. data/handbook/skills/as-idea-review/SKILL.md +26 -0
  18. data/handbook/workflow-instructions/idea/capture-features.wf.md +243 -0
  19. data/handbook/workflow-instructions/idea/capture.wf.md +270 -0
  20. data/handbook/workflow-instructions/idea/prioritize.wf.md +223 -0
  21. data/handbook/workflow-instructions/idea/review.wf.md +93 -0
  22. data/lib/ace/idea/atoms/idea_file_pattern.rb +40 -0
  23. data/lib/ace/idea/atoms/idea_frontmatter_defaults.rb +39 -0
  24. data/lib/ace/idea/atoms/idea_id_formatter.rb +37 -0
  25. data/lib/ace/idea/atoms/idea_validation_rules.rb +89 -0
  26. data/lib/ace/idea/atoms/slug_sanitizer_adapter.rb +6 -0
  27. data/lib/ace/idea/cli/commands/create.rb +98 -0
  28. data/lib/ace/idea/cli/commands/doctor.rb +206 -0
  29. data/lib/ace/idea/cli/commands/list.rb +62 -0
  30. data/lib/ace/idea/cli/commands/show.rb +55 -0
  31. data/lib/ace/idea/cli/commands/status.rb +61 -0
  32. data/lib/ace/idea/cli/commands/update.rb +118 -0
  33. data/lib/ace/idea/cli.rb +75 -0
  34. data/lib/ace/idea/models/idea.rb +39 -0
  35. data/lib/ace/idea/molecules/idea_clipboard_reader.rb +117 -0
  36. data/lib/ace/idea/molecules/idea_config_loader.rb +93 -0
  37. data/lib/ace/idea/molecules/idea_creator.rb +248 -0
  38. data/lib/ace/idea/molecules/idea_display_formatter.rb +165 -0
  39. data/lib/ace/idea/molecules/idea_doctor_fixer.rb +504 -0
  40. data/lib/ace/idea/molecules/idea_doctor_reporter.rb +264 -0
  41. data/lib/ace/idea/molecules/idea_frontmatter_validator.rb +137 -0
  42. data/lib/ace/idea/molecules/idea_llm_enhancer.rb +177 -0
  43. data/lib/ace/idea/molecules/idea_loader.rb +124 -0
  44. data/lib/ace/idea/molecules/idea_mover.rb +78 -0
  45. data/lib/ace/idea/molecules/idea_resolver.rb +57 -0
  46. data/lib/ace/idea/molecules/idea_scanner.rb +56 -0
  47. data/lib/ace/idea/molecules/idea_structure_validator.rb +157 -0
  48. data/lib/ace/idea/organisms/idea_doctor.rb +207 -0
  49. data/lib/ace/idea/organisms/idea_manager.rb +251 -0
  50. data/lib/ace/idea/version.rb +7 -0
  51. data/lib/ace/idea.rb +37 -0
  52. metadata +166 -0
@@ -0,0 +1,270 @@
1
+ ---
2
+ doc-type: workflow
3
+ title: Capture Idea Workflow Instruction
4
+ purpose: Documentation for ace-idea/handbook/workflow-instructions/idea/capture.wf.md
5
+ ace-docs:
6
+ last-updated: 2026-03-01
7
+ last-checked: 2026-03-21
8
+ ---
9
+
10
+ # Capture Idea Workflow Instruction
11
+
12
+ ## Goal
13
+
14
+ Use the ace-idea tool to capture and enhance raw ideas within project context, transforming informal thoughts into structured, contextual ideas ready for future specification phases.
15
+
16
+ ## Prerequisites
17
+
18
+ * `ace-idea` tool available (from dev-tools Ruby gem)
19
+ * Raw idea text or concept to capture
20
+ * LLM provider configured (Google Gemini recommended)
21
+ * Write access to the configured ideas directory (default: `.ace-ideas/`)
22
+
23
+ ## Process Steps
24
+
25
+ 1. **Identify the Idea Source:**
26
+ * Determine the input method for your raw idea:
27
+ * **Direct text**: You have the idea ready as text
28
+ * **Clipboard**: Idea is copied to clipboard
29
+ * **File content**: Idea is stored in a text file
30
+ * Prepare the idea text - can be informal, unstructured, or just a brief concept
31
+
32
+ 2. **Choose Appropriate Command Options:**
33
+ * **Basic usage** (most common):
34
+ ```bash
35
+ ace-idea create "your raw idea text here"
36
+ ```
37
+
38
+ * **From clipboard**:
39
+ ```bash
40
+ ace-idea create --clipboard
41
+ # OR combine with context:
42
+ ace-idea create "Main context" --clipboard
43
+ ```
44
+
45
+ * **With explicit title and tags**:
46
+ ```bash
47
+ ace-idea create "Explicit idea text here" --title "Refined title" --tags ux,ideas
48
+ ```
49
+
50
+ * **With folder placement**:
51
+ ```bash
52
+ # Park uncertain work in _maybe
53
+ ace-idea create "Future experiment" --move-to maybe
54
+
55
+ # Keep low-priority work in _anytime
56
+ ace-idea create "Nice-to-have polish" --move-to anytime
57
+
58
+ # Fresh captures go to root by default (no --move-to needed)
59
+ ace-idea create "New feature idea"
60
+ ```
61
+
62
+ * **With Git commit**:
63
+ ```bash
64
+ ace-idea create "New feature" --git-commit
65
+ ```
66
+
67
+ * **With LLM enhancement**:
68
+ ```bash
69
+ ace-idea create "Complex idea" --llm-enhance
70
+ ```
71
+
72
+ 3. **Execute Idea Capture:**
73
+ * Run the selected `ace-idea create` command
74
+ * The tool will automatically:
75
+ * Create a structured idea file with frontmatter metadata
76
+ * Generate a folder and spec filename using the raw ID and slug
77
+ * Optionally enhance with LLM (if `--llm-enhance` or configured)
78
+ * Optionally commit to git (if `--git-commit` or configured)
79
+ * Store the idea in `.ace-ideas/` or the configured root, with optional folder placement (e.g., `_maybe`, `_anytime`)
80
+ * Monitor the output for the created file path
81
+
82
+ 4. **Verify Idea Creation:**
83
+ * Check that the command completed successfully
84
+ * Note the output file path showing:
85
+ - The configured ideas root (default: `.ace-ideas/`)
86
+ - Optional special folder such as `_maybe`, `_anytime`, or `_archive`
87
+ - Idea directory (format: `{id}-{slug}/`)
88
+ - Idea file (format: `{id}-{slug}.idea.s.md`)
89
+ * Verify the file exists and contains:
90
+ - Frontmatter with `id`, `status`, `title`, `tags`, and `created_at`
91
+ - Content body with your idea details
92
+ * Review the generated content for quality
93
+
94
+ 5. **Document the Captured Idea:**
95
+ * Record the path to the created idea file for future reference
96
+ * Note any follow-up actions or related ideas
97
+ * Consider whether immediate specification work is needed
98
+
99
+ ## Decision Guidance
100
+
101
+ ### When to Use This Workflow
102
+
103
+ **Use capture-idea when:**
104
+ * You have a raw, unstructured idea that needs project context
105
+ * Ideas come from brainstorming, user feedback, or informal discussions
106
+ * You want to preserve ideas for future development cycles
107
+ * Ideas need contextual questions for proper specification later
108
+
109
+ **Don't use capture-idea when:**
110
+ * You already have well-structured requirements (use draft-task instead)
111
+ * The idea is just a quick note (simple text file may suffice)
112
+ * You need immediate implementation (use work-on-task workflow)
113
+
114
+ ### Scope Considerations
115
+
116
+ * **Root ideas** (default): Fresh captures — no `--move-to` needed
117
+ * **Maybe queue** (`--move-to maybe`): Ideas worth revisiting later
118
+ * **Anytime queue** (`--move-to anytime`): Low-priority work with no immediate deadline
119
+ * **Archive** (`--move-to archive`): Completed or retired ideas
120
+
121
+ ## Common Usage Patterns
122
+
123
+ ### Pattern 1: Quick Idea Capture
124
+ ```bash
125
+ # Capture a brief concept immediately
126
+ ace-idea create "Add real-time notifications to the dashboard"
127
+ # => Created: .ace-ideas/8ppq7w-real-time-notifications/8ppq7w-real-time-notifications.idea.s.md
128
+ ```
129
+
130
+ ### Pattern 2: Place an Idea in _maybe
131
+ ```bash
132
+ # Park an idea for later evaluation
133
+ ace-idea create "Migrate to PostgreSQL" --move-to maybe
134
+ # => Created: .ace-ideas/_maybe/8ppq7w-migrate-to-postgresql/8ppq7w-migrate-to-postgresql.idea.s.md
135
+ ```
136
+
137
+ ### Pattern 3: Clipboard Integration
138
+ ```bash
139
+ # Copy idea text to clipboard first, then:
140
+ ace-idea create --clipboard
141
+ # OR combine with main context:
142
+ ace-idea create "Dashboard improvements" --clipboard
143
+ # => Created: .ace-ideas/8ppq7w-dashboard-improvements/8ppq7w-dashboard-improvements.idea.s.md
144
+ ```
145
+
146
+ ### Pattern 4: Enhanced Idea with Git Commit
147
+ ```bash
148
+ # Create enhanced idea and automatically commit
149
+ ace-idea create "Complex refactoring task" --llm-enhance --git-commit
150
+ # => LLM enhances idea, creates file, commits to git
151
+ # => Created: .ace-ideas/8ppq7w-complex-refactoring-task/8ppq7w-complex-refactoring-task.idea.s.md
152
+ ```
153
+
154
+ ### Pattern 5: GTD-Style Folder Organization
155
+ ```bash
156
+ # Uncertain idea
157
+ ace-idea create "Consider switching to TypeScript" --move-to maybe
158
+
159
+ # Low priority idea
160
+ ace-idea create "Add dark mode theme" --move-to anytime
161
+
162
+ # Archive an old idea later
163
+ ace-idea update q7w --move-to archive
164
+ ```
165
+
166
+ ## Error Handling
167
+
168
+ ### Common Issues and Solutions
169
+
170
+ **"No content provided" Error:**
171
+ * **Cause**: Missing idea text argument and no clipboard input
172
+ * **Solution**: Provide idea text: `ace-idea create "your idea"`
173
+ * **Alternative**: Use `--clipboard`
174
+
175
+ **"Could not read from clipboard" Error:**
176
+ * **Cause**: Clipboard tools not available on system (pbpaste/pbcopy on macOS)
177
+ * **Solution**: Use direct text input or ensure clipboard tools are available
178
+ * **Note**: Clipboard functionality requires `ace-support-mac-clipboard` gem
179
+
180
+ **"Invalid target folder" Error:**
181
+ * **Cause**: `--move-to` was given a virtual filter (e.g., `next`) instead of a physical folder
182
+ * **Solution**: Use a physical folder: `maybe`, `anytime`, `archive`, or any custom name. Note: `next` is a virtual filter for listing, not a physical folder — omit `--move-to` to place ideas in root
183
+
184
+ **LLM Enhancement Failures:**
185
+ * **Cause**: API issues, model unavailability, or `--no-llm-enhance` flag
186
+ * **Result**: Tool saves raw idea without LLM enhancement
187
+ * **Action**: Check LLM configuration, network/API keys, or accept basic idea file
188
+ * **Note**: Enhancement is optional; ideas work fine without it
189
+
190
+ **Git Commit Failures:**
191
+ * **Cause**: Git repository issues or `--no-git-commit` flag
192
+ * **Result**: Idea file created but not committed
193
+ * **Action**: Manually commit later or fix git configuration
194
+
195
+ ## Success Criteria
196
+
197
+ * Idea successfully captured in appropriate directory:
198
+ - Root: `.ace-ideas/`
199
+ - Special folder: `.ace-ideas/_maybe/`, `.ace-ideas/_anytime/`, or `.ace-ideas/_archive/`
200
+ * Generated file structure includes:
201
+ - Idea directory (e.g., `8ppq7w-dark-mode/`)
202
+ - Idea file with frontmatter (e.g., `8ppq7w-dark-mode.idea.s.md`)
203
+ * Frontmatter contains required metadata:
204
+ - `id`: Raw idea identifier
205
+ - `status`: Initial status
206
+ - `title`: Human-readable title
207
+ - `tags`: Array of tags
208
+ - `created_at`: Creation timestamp
209
+ * File content includes idea description and details
210
+ * Tool returns created file path for reference
211
+ * No errors during capture process
212
+ * Optional: Git commit created (if configured or requested)
213
+ * Optional: LLM enhancement applied (if configured or requested)
214
+
215
+ ## Integration with Other Workflows
216
+
217
+ ### Natural Follow-up Workflows
218
+
219
+ **After capturing ideas:**
220
+ * **draft-task**: When ready to turn idea into actionable task
221
+ * **draft-release**: During release planning to review captured ideas
222
+ * **create-reflection-note**: To document patterns from multiple ideas
223
+
224
+ **Preparation workflows:**
225
+ * **load-project-context**: If project context files are missing
226
+ * **update-blueprint**: If project structure has changed significantly
227
+
228
+ ## Usage Examples
229
+
230
+ ### Example 1: User Feedback Integration
231
+ ```bash
232
+ # After receiving user feedback: "Users want better mobile experience"
233
+ ace-idea create "Users report difficulties with mobile interface - want better responsive design and touch interactions" --llm-enhance
234
+ # Output: Creates enhanced idea with mobile UX questions and project-specific considerations
235
+ # => .ace-ideas/8ppq7w-mobile-interface-improvements/...
236
+ ```
237
+
238
+ ### Example 2: Technical Improvement Ideas
239
+ ```bash
240
+ # During code review, note performance concerns
241
+ ace-idea create "Database queries in user dashboard are slow - consider caching layer and query optimization" --git-commit
242
+ # Output: Creates idea and commits to git automatically
243
+ # => .ace-ideas/8ppq7w-database-query-optimization/...
244
+ ```
245
+
246
+ ### Example 3: Maybe-Later Feature Ideas
247
+ ```bash
248
+ # Capture future feature for later evaluation
249
+ ace-idea create "Add GraphQL API alongside REST" --move-to maybe
250
+ # Output: Creates idea in the maybe queue for later evaluation
251
+ # => .ace-ideas/_maybe/8ppq7w-graphql-api-alongside-rest/...
252
+ ```
253
+
254
+ ### Example 4: Configuration for Automatic Enhancement
255
+ ```yaml
256
+ # ~/.ace/idea/config.yml
257
+ idea:
258
+ defaults:
259
+ git_commit: true # Always commit new ideas
260
+ llm_enhance: true # Always enhance new captures
261
+ ```
262
+ ```bash
263
+ # Now simple command does both
264
+ ace-idea create "New feature concept"
265
+ # => Automatically enhanced and committed
266
+ ```
267
+
268
+ ---
269
+
270
+ This workflow enables efficient capture and enhancement of raw ideas, ensuring they're preserved with proper project context and structured for future development consideration. The ace-idea tool handles the complexity of context loading and enhancement, providing a simple interface for idea preservation.
@@ -0,0 +1,223 @@
1
+ ---
2
+ doc-type: workflow
3
+ title: Prioritize and Align Ideas
4
+ purpose: Documentation for ace-idea/handbook/workflow-instructions/idea/prioritize.wf.md
5
+ ace-docs:
6
+ last-updated: 2026-03-01
7
+ last-checked: 2026-03-21
8
+ ---
9
+
10
+ # Prioritize and Align Ideas
11
+
12
+ ## Goal
13
+
14
+ Systematically organize, prioritize, and align queued ideas with current project architecture to create an actionable implementation roadmap.
15
+
16
+ ## Prerequisites
17
+
18
+ * Access to the project's ideas directory and current queue folders
19
+ * Understanding of project's architecture patterns
20
+ * Access to project documentation in `docs/` directory
21
+ * Knowledge of existing tools and workflows
22
+
23
+ ## Project Context Loading
24
+
25
+ - Read and follow: `ace-bundle wfi://bundle`
26
+
27
+ ## Process Steps
28
+
29
+ ### 1. **Analyze Current Ideas:**
30
+ * List all files in the project's current idea queues
31
+ * Read each idea file to understand:
32
+ - Problem being solved
33
+ - Proposed solution
34
+ - Expected impact
35
+ - Implementation complexity
36
+ * Group ideas by theme or category
37
+
38
+ **Validation:**
39
+ * All idea files have been read and cataloged
40
+ * Ideas are grouped into logical categories
41
+
42
+ ### 2. **Determine Prioritization Scope:**
43
+ * Define number of ideas to prioritize:
44
+ - Default: Top 10 most impactful
45
+ - Configurable: `--count N` for specific number
46
+ - All: `--all` to process entire backlog
47
+ * Apply prioritization criteria:
48
+ - Impact: Critical > High > Medium > Low
49
+ - Complexity: Hours > Days > Weeks
50
+ - Dependencies: Independent > Few > Many
51
+
52
+ **Validation:**
53
+ * Clear list of ideas to be processed
54
+ * Prioritization rationale documented
55
+
56
+ ### 3. **Research Project Architecture:**
57
+ * Identify project's technical patterns:
58
+ ```bash
59
+ # For Ruby projects
60
+ ls -1 exe/ lib/*/
61
+
62
+ # For Node.js projects
63
+ ls -1 src/ bin/
64
+
65
+ # For generic projects
66
+ find . -type f -name "*.md" | head -20
67
+ ```
68
+ * Review existing tools and utilities
69
+ * Understand naming conventions and structure
70
+ * Identify workflow instruction patterns (if applicable)
71
+
72
+ **Validation:**
73
+ * Project structure documented
74
+ * Key architectural patterns identified
75
+ * Existing tools inventory complete
76
+
77
+ ### 4. **Prioritize Ideas Using Folder Updates:**
78
+ * Use `ace-idea update --move-to` to place ideas into priority folders
79
+ * Priority levels:
80
+ - **High priority** (Critical impact, low complexity): Move to `_next`
81
+ - **Medium priority** (High impact or medium complexity): Move to `_maybe`
82
+ - **Lower priority** (remaining ideas): Move to `_anytime`
83
+
84
+ * Update pattern:
85
+ ```bash
86
+ # Place highest priority ideas in next queue
87
+ ace-idea update <idea-1> --move-to next
88
+
89
+ # Place medium priority ideas in maybe folder
90
+ ace-idea update <idea-2> --move-to maybe
91
+
92
+ # Place lower priority ideas in anytime folder
93
+ ace-idea update <low-priority-idea> --move-to anytime
94
+ ```
95
+
96
+ **How it works:**
97
+ * Updates move idea files between folders (`_next`, `_maybe`, `_anytime`)
98
+ * Ideas are listed per folder when using `ace-idea list --in <folder>`
99
+ * The same command can also update metadata such as `status` when needed
100
+
101
+ **Validation:**
102
+ * Running `ace-idea list --in next` shows high-priority ideas
103
+ * Can re-prioritize later by moving ideas between folders again
104
+
105
+ ### 5. **Align Ideas with Project Architecture:**
106
+ For each prioritized idea:
107
+ * Update file paths to match project structure
108
+ * Reference existing tools and utilities
109
+ * Align with project's architectural patterns
110
+ * Include implementation approach specific to project
111
+ * Add testing strategy appropriate to project
112
+ * Define measurable success metrics
113
+
114
+ Template for aligned idea:
115
+ ```markdown
116
+ # [Improvement Name]
117
+
118
+ ## Intention
119
+ [Clear problem statement]
120
+
121
+ ## Problem It Solves
122
+ **Current Issues:**
123
+ **Impact:**
124
+
125
+ ## Solution Direction
126
+ ### Implementation Approach
127
+ [Project-specific implementation details]
128
+
129
+ ### Integration Points
130
+ [How it fits with existing architecture]
131
+
132
+ ## Implementation Plan
133
+ Phase 1: [Core functionality]
134
+ Phase 2: [Enhancements]
135
+
136
+ ## Testing Strategy
137
+ [Project-appropriate testing approach]
138
+
139
+ ## Success Metrics
140
+ [Measurable outcomes]
141
+ ```
142
+
143
+ **Validation:**
144
+ * Ideas reference correct project paths
145
+ * Implementation aligns with project patterns
146
+ * Testing approach matches project standards
147
+
148
+ ### 6. **Create Implementation Roadmap:**
149
+ Generate `000-implementation-roadmap.md` containing:
150
+ * Executive summary of prioritized improvements
151
+ * Ordered list with effort estimates
152
+ * Implementation timeline (weekly/sprint-based)
153
+ * Technical dependencies and risks
154
+ * Success metrics and governance
155
+
156
+ **Validation:**
157
+ * Roadmap provides clear action plan
158
+ * Timeline is realistic and achievable
159
+ * Dependencies clearly identified
160
+
161
+ ### 7. **Clean Up and Finalize:**
162
+ * Remove any temporary files created during process
163
+ * Verify prioritized ideas are in the expected folders
164
+ * Verify folder contents with `ace-idea list --in next`, `ace-idea list --in maybe`, and `ace-idea list --in anytime`
165
+ * Create summary of changes for commit message
166
+
167
+ **Validation:**
168
+ * No temporary files remain
169
+ * Folder listings reflect the intended priorities
170
+ * `ace-idea list --in next` shows the most actionable ideas
171
+ * Git status shows the expected renamed or moved idea directories
172
+ * Ready for review and commit
173
+
174
+ ## Success Criteria
175
+
176
+ * All selected ideas are placed in the intended priority folders
177
+ * Ideas aligned with current project architecture
178
+ * Implementation roadmap created with clear timeline
179
+ * No broken references or missing dependencies
180
+ * `ace-idea list --in next` displays the highest-priority ideas
181
+ * Changes ready for version control commit
182
+
183
+ ## Error Handling
184
+
185
+ **Missing Architecture Documentation:**
186
+ * **Symptoms:** No docs/ directory or architecture files
187
+ * **Solution:** Infer from project structure and existing code
188
+
189
+ **Conflicting Priorities:**
190
+ * **Symptoms:** Multiple ideas with same impact/complexity
191
+ * **Solution:** Use additional criteria (dependencies, risk, user value)
192
+
193
+ **Large Backlogs (>50 ideas):**
194
+ * **Symptoms:** Too many ideas to process effectively
195
+ * **Solution:** Focus on top 20, schedule remaining for future cycles
196
+
197
+ ## Usage Example
198
+
199
+ > "Organize and prioritize our backlog of 47 improvement ideas, focusing on the top 10 most impactful ones that we can implement this quarter"
200
+
201
+ ## Common Patterns
202
+
203
+ ### For Different Project Types
204
+
205
+ **Ruby/Rails Projects:**
206
+ * Look for `exe/`, `lib/`, `spec/` directories
207
+ * Reference Gemfile for dependencies
208
+ * Align with RSpec testing patterns
209
+
210
+ **Node.js Projects:**
211
+ * Look for `src/`, `bin/`, `test/` directories
212
+ * Reference package.json for dependencies
213
+ * Align with Jest/Mocha testing patterns
214
+
215
+ **Python Projects:**
216
+ * Look for `src/`, `tests/`, `scripts/` directories
217
+ * Reference requirements.txt/pyproject.toml
218
+ * Align with pytest patterns
219
+
220
+ **Generic Projects:**
221
+ * Focus on `docs/` directory structure
222
+ * Identify primary language from file extensions
223
+ * Use general software patterns
@@ -0,0 +1,93 @@
1
+ ---
2
+ doc-type: workflow
3
+ title: Review Idea Workflow Instruction
4
+ purpose: Documentation for ace-idea/handbook/workflow-instructions/idea/review.wf.md
5
+ ace-docs:
6
+ last-updated: 2026-03-02
7
+ last-checked: 2026-03-21
8
+ ---
9
+
10
+ # Review Idea Workflow Instruction
11
+
12
+ ## Goal
13
+
14
+ Critically evaluate an idea for clarity, impact, scope boundaries, and execution readiness. This workflow acts as an adversarial quality gate before converting ideas into implementation tasks.
15
+
16
+ ## When to Use
17
+
18
+ - Reviewing raw idea notes before drafting a task
19
+ - Final synthesis of simulation runs focused on idea quality
20
+ - Evaluating whether an idea is ready for prioritization or needs refinement
21
+
22
+ ## Evaluation Dimensions
23
+
24
+ Evaluate against these six dimensions. Score each as **PASS**, **WEAK**, or **FAIL**.
25
+
26
+ ### 1. Problem Clarity
27
+ - Is the problem concrete and specific?
28
+ - Is the current pain/risk explicitly described?
29
+
30
+ ### 2. Outcome Clarity
31
+ - Is the desired end state measurable?
32
+ - Are success criteria observable and testable?
33
+
34
+ ### 3. Scope Boundaries
35
+ - Are in-scope and out-of-scope boundaries explicit?
36
+ - Are assumptions/defaults documented?
37
+
38
+ ### 4. Feasibility Signals
39
+ - Are technical constraints, dependencies, and risks acknowledged?
40
+ - Is the effort level realistic for the expected value?
41
+
42
+ ### 5. Decision Gaps
43
+ - Are key unknowns listed with concrete questions?
44
+ - Are blocking decisions separated from nice-to-have details?
45
+
46
+ ### 6. Next-Step Readiness
47
+ - Is there a clear immediate next action (draft task, research, reject, etc.)?
48
+ - Could another agent continue work without guessing?
49
+
50
+ ## Output Format
51
+
52
+ Return markdown in this structure:
53
+
54
+ ```markdown
55
+ ## Idea Critique
56
+
57
+ **Verdict:** READY TO DRAFT | NEEDS REFINEMENT | INSUFFICIENT
58
+
59
+ ### Dimension Scores
60
+
61
+ | Dimension | Score | Notes |
62
+ |-----------|-------|-------|
63
+ | Problem Clarity | PASS/WEAK/FAIL | One-line finding |
64
+ | Outcome Clarity | PASS/WEAK/FAIL | One-line finding |
65
+ | Scope Boundaries | PASS/WEAK/FAIL | One-line finding |
66
+ | Feasibility Signals | PASS/WEAK/FAIL | One-line finding |
67
+ | Decision Gaps | PASS/WEAK/FAIL | One-line finding |
68
+ | Next-Step Readiness | PASS/WEAK/FAIL | One-line finding |
69
+
70
+ ### What to Update
71
+ - [Concrete updates to make the idea implementation-ready]
72
+
73
+ ### What Needs Precision
74
+ - [Blocking questions and missing specifics]
75
+
76
+ ### Prioritized Next Actions
77
+ 1. [Highest impact next action]
78
+ 2. [Second action]
79
+ 3. [Third action]
80
+ ```
81
+
82
+ ## Verdict Criteria
83
+
84
+ - **READY TO DRAFT:** No FAIL scores, at most one WEAK score
85
+ - **NEEDS REFINEMENT:** No more than two FAIL scores, or three+ WEAK scores
86
+ - **INSUFFICIENT:** Three or more FAIL scores
87
+
88
+ ## Review Principles
89
+
90
+ - Be adversarial and specific.
91
+ - Demand explicit decisions where ambiguity blocks execution.
92
+ - Prefer concrete, testable suggestions over generic advice.
93
+ - Avoid introducing implementation details beyond the idea stage unless required for feasibility.
@@ -0,0 +1,40 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Ace
4
+ module Idea
5
+ module Atoms
6
+ # Provides glob patterns for finding idea spec files.
7
+ # Ideas use the .idea.s.md extension to distinguish from task .s.md files.
8
+ module IdeaFilePattern
9
+ # Glob pattern for idea spec files within a directory
10
+ FILE_GLOB = "*.idea.s.md"
11
+
12
+ # Full file extension for idea spec files
13
+ FILE_EXTENSION = ".idea.s.md"
14
+
15
+ # Build the spec filename for an idea
16
+ # @param id [String] Raw 6-char b36ts ID
17
+ # @param slug [String] Kebab-case slug
18
+ # @return [String] Spec filename (e.g., "8ppq7w-dark-mode.idea.s.md")
19
+ def self.spec_filename(id, slug)
20
+ "#{id}-#{slug}#{FILE_EXTENSION}"
21
+ end
22
+
23
+ # Build the folder name for an idea
24
+ # @param id [String] Raw 6-char b36ts ID
25
+ # @param slug [String] Kebab-case slug
26
+ # @return [String] Folder name (e.g., "8ppq7w-dark-mode")
27
+ def self.folder_name(id, slug)
28
+ "#{id}-#{slug}"
29
+ end
30
+
31
+ # Check if a filename matches the idea spec pattern
32
+ # @param filename [String] Filename to check
33
+ # @return [Boolean] True if it's an idea spec file
34
+ def self.idea_file?(filename)
35
+ filename.to_s.end_with?(FILE_EXTENSION)
36
+ end
37
+ end
38
+ end
39
+ end
40
+ end
@@ -0,0 +1,39 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "time"
4
+
5
+ module Ace
6
+ module Idea
7
+ module Atoms
8
+ # Provides default frontmatter values for idea spec files.
9
+ # Generates the canonical YAML frontmatter block for new ideas.
10
+ module IdeaFrontmatterDefaults
11
+ # Build frontmatter hash for a new idea
12
+ # @param id [String] Raw 6-char b36ts ID
13
+ # @param title [String] Idea title
14
+ # @param tags [Array<String>] List of tags (default: [])
15
+ # @param status [String] Initial status (default: "pending")
16
+ # @param created_at [Time] Creation time (default: now)
17
+ # @return [Hash] Frontmatter hash ready for YAML serialization
18
+ def self.build(id:, title:, tags: [], status: "pending", created_at: Time.now.utc)
19
+ {
20
+ "id" => id,
21
+ "status" => status,
22
+ "title" => title,
23
+ "tags" => Array(tags),
24
+ "created_at" => created_at.strftime("%Y-%m-%d %H:%M:%S")
25
+ }
26
+ end
27
+
28
+ # Serialize frontmatter hash to YAML block string.
29
+ # Delegates to the shared FrontmatterSerializer atom.
30
+ # @param frontmatter [Hash] Frontmatter data
31
+ # @return [String] YAML frontmatter block including delimiters
32
+ def self.serialize(frontmatter)
33
+ require "ace/support/items"
34
+ Ace::Support::Items::Atoms::FrontmatterSerializer.serialize(frontmatter)
35
+ end
36
+ end
37
+ end
38
+ end
39
+ end
@@ -0,0 +1,37 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "ace/b36ts"
4
+
5
+ module Ace
6
+ module Idea
7
+ module Atoms
8
+ # Generates and formats raw b36ts IDs for ideas.
9
+ # Ideas use raw 6-char b36ts IDs without type markers.
10
+ # Example: "8ppq7w" (no ".t." or ".i." separator)
11
+ class IdeaIdFormatter
12
+ # Generate a new raw 6-char b36ts ID for an idea
13
+ # @param time [Time] Time to encode (default: now)
14
+ # @return [String] 6-character raw b36ts ID (e.g., "8ppq7w")
15
+ def self.generate(time = Time.now.utc)
16
+ Ace::B36ts.encode(time, format: :"2sec")
17
+ end
18
+
19
+ # Validate that a string is a valid raw idea ID
20
+ # @param id [String] The ID to validate
21
+ # @return [Boolean] True if valid 6-char b36ts ID
22
+ def self.valid?(id)
23
+ return false if id.nil? || id.empty?
24
+
25
+ Ace::B36ts.valid?(id)
26
+ end
27
+
28
+ # Decode a raw idea ID to the time it was created
29
+ # @param id [String] Raw 6-char b36ts ID
30
+ # @return [Time] The time encoded in the ID
31
+ def self.decode_time(id)
32
+ Ace::B36ts.decode(id)
33
+ end
34
+ end
35
+ end
36
+ end
37
+ end