# Learnings Log

This file captures corrections, knowledge gaps, and best practices discovered during agent operation.

## Format

Each entry:

```markdown
## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending | in_progress | resolved | wont_fix | promoted
**Area**: frontend | backend | infra | tests | docs | config

### Summary
One-line description

### Details
Full context

### Suggested Action
Specific improvement

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-YYYYMMDD-XXX
- Pattern-Key: simplify.dead_code | harden.input_validation (optional)
- Recurrence-Count: 1
- First-Seen: YYYY-MM-DD
- Last-Seen: YYYY-MM-DD

---
```

---

## Existing Learnings

### [LRN-20260331-001] mandatory_skill_activation

**Logged**: 2026-03-31T02:26:00Z
**Priority**: high
**Status**: in_progress
**Area**: orchestration

### Summary
Always invoke using-superpowers skill before any response or action.

### Details
User instruction: Skill using-superpowers must be activated at every interaction — startup, reset, tasks, ClawTeam usage, and chats.

### Suggested Action
- Before any task or response, read and apply using-superpowers skill
- Treat it as mandatory, not optional
- Check for applicable skills before any action

### Metadata
- Source: user_instruction
- Related Files: skills/using-superpowers/SKILL.md
- Tags: mandatory, skill_invocation
- Pattern-Key: mandatory.skill_invocation
- Recurrence-Count: 1
- First-Seen: 2026-03-31
- Last-Seen: 2026-03-31

---

### [LRN-20260331-004] clawteam_self_then_peer_then_leader_review_workflow

**Logged**: 2026-03-31T09:54:00Z
**Priority**: high
**Status**: pending
**Area**: orchestration

### Summary
Enforce three-tier code review for ClawTeam workers: self-review → peer review → leader review.

### Details
User-defined workflow for multi-agent code reviews in ClawTeam:
1. Each worker must self-review their completed work before any peer review.
2. Other workers then review the code.
3. Finally, the leader (orchestrator) reviews and approves.

User provided detailed review prompt (modified for team context):

**Review Prompt**:
- **Plan Alignment Analysis**: Compare against original planning doc; identify deviations; assess if justified improvements or problematic; verify all planned functionality implemented.
- **Code Quality Assessment**: Check adherence to patterns/conventions; error handling, type safety, defensive programming; code organization, naming, maintainability; test coverage/quality; security/performance issues.
- **Architecture and Design Review**: SOLID principles, architectural patterns; separation of concerns, loose coupling; integration with existing systems; scalability/extensibility.
- **Documentation and Standards**: Appropriate comments/docs; file headers, function docs, inline comments accuracy; adherence to project coding standards.
- **Issue Identification and Recommendations**: Categorize: Critical (must fix), Important (should fix), Suggestions (nice to have); provide specific examples and actionable recommendations; explain plan deviations (problematic vs beneficial); suggest improvements with code examples.
- **Communication Protocol**: For significant deviations, ask coding agent to review/confirm; if plan issues, recommend plan updates; for implementation problems, provide clear guidance; always acknowledge strengths before issues.

This replaces ad-hoc review practices and ensures quality control in distributed development.

### Suggested Action
- Integrate this review workflow into clawteam-multi-agent-coordination skill guidance
- Add prompts/checklists for each review tier (self, peer, leader)
- Create automation or reminders to enforce the sequence
- Document this as mandatory in AGENTS.md under ClawTeam workflows
- Consider adding git hooks or task status transitions that gate peer/leader review until self-review is done

### Metadata
- Source: user_instruction
- Related Files: skills/clawteam-multi-agent-coordination/SKILL.md, AGENTS.md
- Tags: review, quality, multi-agent, workflow
- Pattern-Key: orchestration.three_tier_review
- Recurrence-Count: 1
- First-Seen: 2026-03-31
- Last-Seen: 2026-03-31

---

### [LRN-20260331-003] use_clawteam_cli_not_session_spawn

**Logged**: 2026-03-31T09:48:00Z
**Priority**: high
**Status**: pending
**Area**: infra

### Summary
Never use sessions_spawn for multi-agent coordination; always use ClawTeam CLI (clawteam-multi-agent-coordination skill).

### Details
User instruction: For any multi-agent work (creating teams, spawning agents, assigning tasks, monitoring progress), do NOT use OpenClaw's session spawn mechanism (sessions_spawn, subagents). Instead, always use the ClawTeam CLI following the clawteam-multi-agent-coordination skill. This ensures proper task management, git worktree isolation, agent messaging, kanban board, and recovery tooling.

### Suggested Action
- When multi-agent coordination is needed, invoke clawteam-multi-agent-coordination skill first
- Use clawteam commands: spawn-team, task create, spawn, board show/attach, inbox send/receive, workspace merge
- Update AGENTS.md to explicitly state: "For tasks requiring multiple agents, use ClawTeam CLI; avoid sessions_spawn/subagents for coordination"
- Remove/replace any existing patterns that use subagents for parallel work

### Metadata
- Source: user_instruction
- Related Files: skills/clawteam-multi-agent-coordination/SKILL.md, AGENTS.md
- Tags: multi-agent, clawteam, sessions_spawn, best_practice
- Pattern-Key: orchestration.clawteam_over_subagents
- Recurrence-Count: 1
- First-Seen: 2026-03-31
- Last-Seen: 2026-03-31

---

### [LRN-20260331-002] production_ready_not_mvp

**Logged**: 2026-03-31T02:50:00Z
**Priority**: critical
**Status**: in_progress
**Area**: orchestration

### Summary
All projects must deliver production-ready, polished products, not barebones MVP.

### Details
User explicitly stated: "với mọi dự án thì tôi đều muốn mọi thứ (kết quả) phải thật hoàn thiện, ra được product thật và có thể sử dụng thật chứ không phải bản MVP sơ sài". This is a core quality standard: no quick-and-dirty implementations, no "good enough for now" shortcuts. Every deliverable should be fully functional, responsive, accessible, error-handled, and deployable.

### Suggested Action
- In planning phase, define acceptance criteria as "production-ready" features (responsive design, error handling, testing, accessibility, SEO, performance)
- During implementation, include polish tasks (animations, hover states, mobile layouts, form validation, loading states)
- Before marking complete, run verification checks (build success, no console errors, responsive test, accessibility audit)
- Avoid technical debt shortcuts; invest in clean architecture and maintainable code from the start
- In code reviews, check for completeness, not just functionality

### Metadata
- Source: user_instruction
- Related Files: docs/superpowers/plans/*.md
- Tags: quality, production-ready, no-mvp
- Pattern-Key: quality.standard.production_ready
- Recurrence-Count: 1
- First-Seen: 2026-03-31
- Last-Seen: 2026-03-31

---