| name | log-insight |
| description | Log a technical insight to docs/insights-log.md immediately. Do not defer — sessions can clear. TRIGGER when the user says "log this insight", "that's worth noting", "remember this", "note this gotcha", "TIL", "important discovery", "capture this learning", or any request to record a technical observation. |
| argument-hint | <topic> <insight text> |
Log Technical Insight
Immediately add an entry to docs/insights-log.md.
Current Context
- Branch: !
git branch --show-current
- Milestone: detected from branch name
What to Log
Arguments: $ARGUMENTS
Insights are non-obvious technical observations discovered during implementation:
- Platform quirks and gotchas
- Architectural trade-offs discovered during implementation
- Debugging techniques that saved significant time
- Performance observations
- Patterns worth remembering across sessions
Entry Format
Add a new row to the insights log table:
| Date | Milestone | Topic | Insight | Verification | Status |
|---|
| [today] | [from branch] | [hierarchical tag] | [the observation] | [how to verify] | Raw |
Topic Tags (Hierarchical)
Use format like: Platform/Area, Framework/Feature, Architecture/Pattern, Testing/Approach
After Logging
Check promotion rules:
- 3+ insights on same topic → Suggest creating a Learning Note in
docs/learning-notes/
- Architectural decision with trade-offs → Suggest creating an ADR in
docs/architecture/
- Recurring gotcha → Suggest adding to CLAUDE.md
Report the promotion check result after logging.
