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.
- checksums.yaml +7 -0
- data/.ace-defaults/idea/config.yml +21 -0
- data/.ace-defaults/nav/protocols/wfi-sources/ace-idea.yml +19 -0
- data/CHANGELOG.md +387 -0
- data/README.md +42 -0
- data/Rakefile +13 -0
- data/docs/demo/ace-idea-getting-started.gif +0 -0
- data/docs/demo/ace-idea-getting-started.tape.yml +44 -0
- data/docs/demo/fixtures/README.md +3 -0
- data/docs/demo/fixtures/sample.txt +1 -0
- data/docs/getting-started.md +102 -0
- data/docs/handbook.md +39 -0
- data/docs/usage.md +320 -0
- data/exe/ace-idea +22 -0
- data/handbook/skills/as-idea-capture/SKILL.md +25 -0
- data/handbook/skills/as-idea-capture-features/SKILL.md +26 -0
- data/handbook/skills/as-idea-review/SKILL.md +26 -0
- data/handbook/workflow-instructions/idea/capture-features.wf.md +243 -0
- data/handbook/workflow-instructions/idea/capture.wf.md +270 -0
- data/handbook/workflow-instructions/idea/prioritize.wf.md +223 -0
- data/handbook/workflow-instructions/idea/review.wf.md +93 -0
- data/lib/ace/idea/atoms/idea_file_pattern.rb +40 -0
- data/lib/ace/idea/atoms/idea_frontmatter_defaults.rb +39 -0
- data/lib/ace/idea/atoms/idea_id_formatter.rb +37 -0
- data/lib/ace/idea/atoms/idea_validation_rules.rb +89 -0
- data/lib/ace/idea/atoms/slug_sanitizer_adapter.rb +6 -0
- data/lib/ace/idea/cli/commands/create.rb +98 -0
- data/lib/ace/idea/cli/commands/doctor.rb +206 -0
- data/lib/ace/idea/cli/commands/list.rb +62 -0
- data/lib/ace/idea/cli/commands/show.rb +55 -0
- data/lib/ace/idea/cli/commands/status.rb +61 -0
- data/lib/ace/idea/cli/commands/update.rb +118 -0
- data/lib/ace/idea/cli.rb +75 -0
- data/lib/ace/idea/models/idea.rb +39 -0
- data/lib/ace/idea/molecules/idea_clipboard_reader.rb +117 -0
- data/lib/ace/idea/molecules/idea_config_loader.rb +93 -0
- data/lib/ace/idea/molecules/idea_creator.rb +248 -0
- data/lib/ace/idea/molecules/idea_display_formatter.rb +165 -0
- data/lib/ace/idea/molecules/idea_doctor_fixer.rb +504 -0
- data/lib/ace/idea/molecules/idea_doctor_reporter.rb +264 -0
- data/lib/ace/idea/molecules/idea_frontmatter_validator.rb +137 -0
- data/lib/ace/idea/molecules/idea_llm_enhancer.rb +177 -0
- data/lib/ace/idea/molecules/idea_loader.rb +124 -0
- data/lib/ace/idea/molecules/idea_mover.rb +78 -0
- data/lib/ace/idea/molecules/idea_resolver.rb +57 -0
- data/lib/ace/idea/molecules/idea_scanner.rb +56 -0
- data/lib/ace/idea/molecules/idea_structure_validator.rb +157 -0
- data/lib/ace/idea/organisms/idea_doctor.rb +207 -0
- data/lib/ace/idea/organisms/idea_manager.rb +251 -0
- data/lib/ace/idea/version.rb +7 -0
- data/lib/ace/idea.rb +37 -0
- 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
|