docs: expand scope and add comprehensive documentation
Create README.md and enhance AGENTS.md to position this as an extensible framework for any Opencode skills and agents, not just PARA/task management. Includes installation, development workflow, code style guidelines, and Nix flake integration patterns.
This commit is contained in:
m3tm3re
85
skill/reflection/references/command-usage.md
Normal file
85
skill/reflection/references/command-usage.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Reflection Command Usage
|
||||
|
||||
## Toggle Commands
|
||||
|
||||
### Enable Reflection Mode
|
||||
```
|
||||
/reflection on
|
||||
```
|
||||
|
||||
**Effect:** Enables automatic detection of correction signals during conversation. I will proactively suggest skill improvements when patterns are detected.
|
||||
|
||||
### Disable Reflection Mode
|
||||
```
|
||||
/reflection off
|
||||
```
|
||||
|
||||
**Effect:** Disables automatic detection. Reflection only occurs when explicitly requested.
|
||||
|
||||
### Check Status
|
||||
```
|
||||
/reflection status
|
||||
```
|
||||
|
||||
**Effect:** Shows whether reflection mode is currently on or off.
|
||||
|
||||
## Behavior by Mode
|
||||
|
||||
### Mode: ON
|
||||
|
||||
**Automatic triggers:**
|
||||
- User corrects same thing 2+ times → Offer reflection
|
||||
- Explicit corrections detected ("No, do it this way") → Ask "Should I reflect on [skill]?"
|
||||
- After skill usage with clear signals → Proactive suggestion
|
||||
|
||||
**Example:**
|
||||
```
|
||||
User: "No, run tests before committing, not after"
|
||||
[conversation continues]
|
||||
User: "Again, tests must run first"
|
||||
|
||||
Agent: "I notice you've corrected the workflow order twice.
|
||||
Should I reflect on the relevant skill to add this constraint?"
|
||||
```
|
||||
|
||||
### Mode: OFF (Default)
|
||||
|
||||
**Manual triggers only:**
|
||||
- User says "reflect", "improve", "learn from this"
|
||||
- User explicitly asks to analyze skill
|
||||
|
||||
**Example:**
|
||||
```
|
||||
User: "Reflect on the task-management skill"
|
||||
|
||||
Agent: [Runs full reflection workflow]
|
||||
```
|
||||
|
||||
## Session Persistence
|
||||
|
||||
Reflection mode is **session-scoped**:
|
||||
- Setting persists for current conversation
|
||||
- Resets to OFF for new sessions
|
||||
- Use `/reflection on` at session start if desired
|
||||
|
||||
## When to Use Each Mode
|
||||
|
||||
### Use ON when:
|
||||
- Actively developing/tuning a new skill
|
||||
- Testing skill behavior with real usage
|
||||
- Learning preferences for a new domain
|
||||
- Want proactive improvement suggestions
|
||||
|
||||
### Use OFF when:
|
||||
- Skills are stable and working well
|
||||
- Don't want interruptions
|
||||
- Only need reflection occasionally
|
||||
- Prefer manual control
|
||||
|
||||
## Integration with Skill
|
||||
|
||||
The reflection skill checks conversation context for mode state:
|
||||
- Looks for recent `/reflection on` or `/reflection off` commands
|
||||
- Defaults to OFF if no command found
|
||||
- Auto-triggers only when ON and signals detected
|
||||
- Always responds to explicit "reflect" requests regardless of mode
|
||||
126
skill/reflection/references/rating-guidelines.md
Normal file
126
skill/reflection/references/rating-guidelines.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Rating Guidelines
|
||||
|
||||
How to classify findings from conversation analysis.
|
||||
|
||||
## Rating Criteria
|
||||
|
||||
### High Priority (Explicit Constraints)
|
||||
|
||||
**Definition:** Direct corrections or explicit rules that MUST be followed.
|
||||
|
||||
**Characteristics:**
|
||||
- User explicitly states a constraint
|
||||
- Correction of incorrect behavior
|
||||
- Safety or correctness requirements
|
||||
- Repeated violations cause frustration
|
||||
|
||||
**Examples:**
|
||||
- "Never commit without asking first"
|
||||
- "Always use TypeScript, not JavaScript"
|
||||
- "You forgot to run tests before committing"
|
||||
- "Don't use global state"
|
||||
|
||||
**Action:** These become hard constraints in the skill documentation.
|
||||
|
||||
**Format in OBSERVATIONS.md:**
|
||||
```markdown
|
||||
## HIGH: [Constraint Title]
|
||||
**Context:** [Which skill/scenario]
|
||||
**Signal:** [What the user said/did]
|
||||
**Constraint:** [The specific rule to follow]
|
||||
**Proposed Change:** [Exact text to add to skill]
|
||||
```
|
||||
|
||||
### Medium Priority (Preferences & Patterns)
|
||||
|
||||
**Definition:** Approaches that work well or user preferences that improve workflow.
|
||||
|
||||
**Characteristics:**
|
||||
- Positive reinforcement from user
|
||||
- Patterns that user adopts repeatedly
|
||||
- Workflow optimizations
|
||||
- Style preferences
|
||||
|
||||
**Examples:**
|
||||
- "That output format is perfect, use that"
|
||||
- User consistently requests bullet points over paragraphs
|
||||
- User prefers parallel tool execution
|
||||
- "I like how you broke that down"
|
||||
|
||||
**Action:** These become preferred approaches or default patterns in skills.
|
||||
|
||||
**Format in OBSERVATIONS.md:**
|
||||
```markdown
|
||||
## MEDIUM: [Preference Title]
|
||||
**Context:** [Which skill/scenario]
|
||||
**Signal:** [What the user said/did]
|
||||
**Preference:** [The preferred approach]
|
||||
**Rationale:** [Why this works well]
|
||||
**Proposed Change:** [Suggested skill update]
|
||||
```
|
||||
|
||||
### Low Priority (Observations)
|
||||
|
||||
**Definition:** Contextual insights, minor preferences, or exploratory findings.
|
||||
|
||||
**Characteristics:**
|
||||
- Environmental context
|
||||
- Tentative patterns (need more data)
|
||||
- Nice-to-have improvements
|
||||
- Exploratory feedback
|
||||
|
||||
**Examples:**
|
||||
- User tends to work on deep tasks in morning
|
||||
- User sometimes asks for alternative approaches
|
||||
- User occasionally needs extra context
|
||||
- Formatting preferences for specific outputs
|
||||
|
||||
**Action:** Document for future consideration. May become higher priority with more evidence.
|
||||
|
||||
**Format in OBSERVATIONS.md:**
|
||||
```markdown
|
||||
## LOW: [Observation Title]
|
||||
**Context:** [Which skill/scenario]
|
||||
**Signal:** [What was noticed]
|
||||
**Observation:** [The pattern or insight]
|
||||
**Potential Action:** [Possible future improvement]
|
||||
```
|
||||
|
||||
## Classification Decision Tree
|
||||
|
||||
```
|
||||
1. Did user explicitly correct behavior?
|
||||
YES → HIGH
|
||||
NO → Continue
|
||||
|
||||
2. Did user express satisfaction with approach?
|
||||
YES → Was it repeated/adopted as pattern?
|
||||
YES → MEDIUM
|
||||
NO → LOW
|
||||
NO → Continue
|
||||
|
||||
3. Is this a repeated pattern (3+ instances)?
|
||||
YES → MEDIUM
|
||||
NO → LOW
|
||||
|
||||
4. Is this exploratory/tentative?
|
||||
YES → LOW
|
||||
```
|
||||
|
||||
## Edge Cases
|
||||
|
||||
**Implicit corrections (repeated fixes by user):**
|
||||
- First instance: LOW (observe)
|
||||
- Second instance: MEDIUM (pattern emerging)
|
||||
- Third instance: HIGH (clear constraint)
|
||||
|
||||
**Contradictory signals:**
|
||||
- Document both
|
||||
- Note the contradiction
|
||||
- Mark for user clarification
|
||||
|
||||
**Context-dependent preferences:**
|
||||
- Rate based on specificity
|
||||
- Document the context clearly
|
||||
- If context is always present: MEDIUM
|
||||
- If context is occasional: LOW
|
||||
79
skill/reflection/references/signal-patterns.md
Normal file
79
skill/reflection/references/signal-patterns.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# User Correction Signal Patterns
|
||||
|
||||
Patterns that indicate the user is correcting or refining the agent's behavior.
|
||||
|
||||
## High Priority Signals (Explicit Corrections)
|
||||
|
||||
**Direct corrections:**
|
||||
- "No, that's not right..."
|
||||
- "Actually, you should..."
|
||||
- "Don't do X, instead do Y"
|
||||
- "That's incorrect..."
|
||||
- "You misunderstood..."
|
||||
|
||||
**Explicit instructions:**
|
||||
- "Always..." / "Never..."
|
||||
- "From now on..."
|
||||
- "Make sure to..."
|
||||
- "Remember to..."
|
||||
|
||||
**Repeated clarifications:**
|
||||
- User re-explains the same point multiple times
|
||||
- User provides same instruction in different words
|
||||
- User corrects same mistake in multiple sessions
|
||||
|
||||
**Workflow corrections:**
|
||||
- "You skipped step X"
|
||||
- "You should have done Y first"
|
||||
- "That's the wrong order"
|
||||
|
||||
## Medium Priority Signals (Effective Patterns)
|
||||
|
||||
**Positive reinforcement:**
|
||||
- "That's perfect"
|
||||
- "Exactly what I needed"
|
||||
- "Great, keep doing it this way"
|
||||
- "Yes, that's the right approach"
|
||||
|
||||
**User adopts the pattern:**
|
||||
- User requests same workflow multiple times
|
||||
- User references previous successful interaction
|
||||
- User asks to "do it like last time"
|
||||
|
||||
**Implicit preferences:**
|
||||
- User consistently asks for specific format
|
||||
- User regularly requests certain tools/approaches
|
||||
- Patterns in how user phrases requests
|
||||
|
||||
## Low Priority Signals (Observations)
|
||||
|
||||
**General feedback:**
|
||||
- "Hmm, interesting..."
|
||||
- "I see..."
|
||||
- Neutral acknowledgments
|
||||
|
||||
**Exploratory questions:**
|
||||
- "What if we tried..."
|
||||
- "Could you also..."
|
||||
- "I wonder if..."
|
||||
|
||||
**Context clues:**
|
||||
- Time of day patterns
|
||||
- Task batching preferences
|
||||
- Communication style preferences
|
||||
|
||||
**Environment signals:**
|
||||
- Tools user prefers
|
||||
- File organization patterns
|
||||
- Workflow preferences
|
||||
|
||||
## Anti-Patterns (Not Corrections)
|
||||
|
||||
**Questions about capabilities:**
|
||||
- "Can you do X?" (not a correction, just inquiry)
|
||||
|
||||
**Exploration:**
|
||||
- "Let's try something different" (exploration, not correction)
|
||||
|
||||
**Context changes:**
|
||||
- "Now let's work on Y" (topic shift, not correction)
|
||||
Reference in New Issue
Block a user