Initial commit
This commit is contained in:
Zhongwei Li
242
commands/ace-learn.md
Normal file
242
commands/ace-learn.md
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
description: Capture learning from completed work interactively
|
||||
---
|
||||
|
||||
# ACE Learn
|
||||
|
||||
Manually capture patterns and lessons learned from your recent work using Claude Code's native UI.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace:learn`, follow these steps:
|
||||
|
||||
### Step 1: Gather Information with AskUserQuestion
|
||||
|
||||
Use the AskUserQuestion tool to collect learning details:
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "What task did you just complete?",
|
||||
header: "Task",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Implemented new feature",
|
||||
description: "Built new functionality or component"
|
||||
},
|
||||
{
|
||||
label: "Fixed bug or issue",
|
||||
description: "Debugged and resolved a problem"
|
||||
},
|
||||
{
|
||||
label: "Refactored code",
|
||||
description: "Improved code structure or performance"
|
||||
},
|
||||
{
|
||||
label: "Integrated API/library",
|
||||
description: "Connected external service or tool"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Then ask for task description in "Other" field or follow-up question.
|
||||
|
||||
### Step 2: Ask for Success Status
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Was the task successful?",
|
||||
header: "Outcome",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Success",
|
||||
description: "Task completed successfully"
|
||||
},
|
||||
{
|
||||
label: "Partial success",
|
||||
description: "Completed but with issues or compromises"
|
||||
},
|
||||
{
|
||||
label: "Failed",
|
||||
description: "Task failed or was abandoned"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Ask for Lessons Learned
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "What did you learn? (key insights, gotchas, solutions)",
|
||||
header: "Lessons",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Enter lessons in 'Other' field",
|
||||
description: "Describe insights, gotchas, best practices discovered"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
User will provide detailed lessons in the "Other" text input.
|
||||
|
||||
### Step 4: Call ce-ace CLI with Flags
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Read context from .claude/settings.json
|
||||
ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
# Also try env wrapper format
|
||||
if [ -z "$ORG_ID" ] || [ -z "$PROJECT_ID" ]; then
|
||||
ORG_ID=$(jq -r '.env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
fi
|
||||
|
||||
if [ -z "$PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace:configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📚 [ACE Learning] Capturing patterns from your work..."
|
||||
echo ""
|
||||
|
||||
# Build ce-ace command based on success status
|
||||
if [ "$SUCCESS_STATUS" = "Success" ]; then
|
||||
SUCCESS_FLAG="--success"
|
||||
elif [ "$SUCCESS_STATUS" = "Failed" ]; then
|
||||
SUCCESS_FLAG="--failure"
|
||||
else
|
||||
# Partial success - treat as success with note in output
|
||||
SUCCESS_FLAG="--success"
|
||||
LESSONS_LEARNED="Partial success: $LESSONS_LEARNED"
|
||||
fi
|
||||
|
||||
# Call ce-ace learn with flags
|
||||
if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" \
|
||||
learn \
|
||||
--task "$TASK_DESCRIPTION" \
|
||||
$SUCCESS_FLAG \
|
||||
--output "$LESSONS_LEARNED"
|
||||
else
|
||||
# Single-org mode (no --org flag)
|
||||
ce-ace --json --project "$PROJECT_ID" \
|
||||
learn \
|
||||
--task "$TASK_DESCRIPTION" \
|
||||
$SUCCESS_FLAG \
|
||||
--output "$LESSONS_LEARNED"
|
||||
fi
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ Patterns captured successfully!"
|
||||
echo " Run /ace:status to see updated playbook"
|
||||
else
|
||||
echo "❌ Failed to capture patterns"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Implementation Notes for Claude
|
||||
|
||||
**Key Points:**
|
||||
1. **Always use AskUserQuestion** for user input (Claude Code native UI)
|
||||
2. **Map user selections** to appropriate values:
|
||||
- "Success" → `--success` flag
|
||||
- "Failed" → `--failure` flag
|
||||
- "Partial success" → `--success` with note in output
|
||||
3. **Extract task description** from user's "Other" input or category selection
|
||||
4. **Extract lessons learned** from "Other" text input
|
||||
5. **Handle both org formats**: Direct (`orgId`) and env wrapper (`env.ACE_ORG_ID`)
|
||||
|
||||
**Error Handling:**
|
||||
- Check ce-ace is installed
|
||||
- Verify project context exists
|
||||
- Provide clear error messages
|
||||
- Show success confirmation with next steps
|
||||
|
||||
## When to Use
|
||||
|
||||
✅ **Use /ace:learn after**:
|
||||
- Implementing new features
|
||||
- Debugging and fixing issues
|
||||
- Discovering edge cases or gotchas
|
||||
- Integrating APIs or libraries
|
||||
- Making architectural decisions
|
||||
- Learning something non-obvious
|
||||
|
||||
❌ **Skip for**:
|
||||
- Trivial changes
|
||||
- Simple Q&A
|
||||
- Reading/exploring code only
|
||||
- No new insights gained
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
User: /ace:learn
|
||||
|
||||
Claude: [Shows AskUserQuestion UI]
|
||||
Question 1: What task did you just complete?
|
||||
User selects: "Fixed bug or issue"
|
||||
User types in Other: "Debugged intermittent test failures in async database operations"
|
||||
|
||||
Claude: [Shows AskUserQuestion UI]
|
||||
Question 2: Was the task successful?
|
||||
User selects: "Success"
|
||||
|
||||
Claude: [Shows AskUserQuestion UI]
|
||||
Question 3: What did you learn?
|
||||
User types in Other: "Root cause was missing await on database.close() causing connection pool exhaustion. Intermittent failures in async code often indicate missing await statements. Always check async cleanup functions."
|
||||
|
||||
Claude runs:
|
||||
ce-ace --json --org "org_xxx" --project "prj_xxx" learn \
|
||||
--task "Debugged intermittent test failures in async database operations" \
|
||||
--success \
|
||||
--output "Root cause was missing await on database.close() causing connection pool exhaustion. Intermittent failures in async code often indicate missing await statements. Always check async cleanup functions."
|
||||
|
||||
✅ Patterns captured successfully!
|
||||
Run /ace:status to see updated playbook
|
||||
```
|
||||
|
||||
## What Gets Captured
|
||||
|
||||
The learning event sent to ACE includes:
|
||||
- **Task description**: Brief summary of the work
|
||||
- **Success/failure status**: Outcome of the task
|
||||
- **Lessons learned**: Key insights, gotchas, solutions, best practices
|
||||
- **Timestamp**: When the learning was captured
|
||||
- **Project context**: Organization and project IDs
|
||||
|
||||
The ACE server's Reflector analyzes this and the Curator updates the playbook with new patterns.
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:status` - View playbook statistics
|
||||
- `/ace:patterns` - Browse learned patterns
|
||||
- `/ace:search <query>` - Find relevant patterns
|
||||
- `/ace:bootstrap` - Initialize from codebase
|
||||
Reference in New Issue
Block a user