# 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

---
## New Learnings — 2026-04-06 (ClawTeam Templates & Dev Team Expansion)

### [LRN-20260406-001] use_clawteam_templates_for_team_creation

**Logged**: 2026-04-06T07:25:00Z
**Priority**: high
**Status**: resolved
**Area**: orchestration

### Summary
When a requested team type doesn't exist, first check `~/.clawteam/templates/` for a matching template before creating a team from scratch.

### Details
User instruction: If dev-team (or any team type) doesn't exist, look in `~/.clawteam/templates/` directory first. Templates provide pre-configured roles, tasks, and worker instructions. Available templates:
- `dev-team.toml` — Tech Lead + Full-stack + Frontend + Backend + UX/UI
- `qc-team.toml` — QC Lead + Code Reviewer + Test Engineer + Acceptance Auditor

Before spawning any team, run `ls ~/.clawteam/templates/` to see what's available. If template exists, use it as the base configuration.

### Suggested Action
- Always check `~/.clawteam/templates/` when user requests team creation
- If template exists, use it (modify if needed)
- If no template exists, create one from scratch and save to templates for future reuse

### Metadata
- Source: user_instruction
- Related Files: ~/.clawteam/templates/dev-team.toml, ~/.clawteam/templates/qc-team.toml
- Tags: clawteam, templates, team-creation
- Pattern-Key: orchestration.use_templates_for_teams
- Recurrence-Count: 1
- First-Seen: 2026-04-06

---

### [LRN-20260406-002] dev_team_includes_qc_and_devops

**Logged**: 2026-04-06T07:30:00Z
**Priority**: high
**Status**: resolved
**Area**: orchestration

### Summary
Dev team must include QC (Quality Control) and DevOps roles. Updated dev-team.toml template to add `qc-lead`, `qa-engineer`, and `devops-engineer` agents.

### Details
User explicitly requested adding 1 QC and 1 DevOps to the dev-team template. Updated `~/.clawteam/templates/dev-team.toml` with:
- `qc-lead` — Code quality gate, review coordination, acceptance criteria
- `qa-engineer` — Test coverage, TDD compliance, edge case validation, regression tests
- `devops-engineer` — CI/CD, Docker, deployment, monitoring, infrastructure

Also added initial tasks for QC (quality criteria definition) and DevOps (CI pipeline setup).

### Suggested Action
- When spawning dev teams, always include QC and DevOps members
- QC runs after feature implementation (dependent tasks)
- DevOps works in parallel for CI/CD setup early

### Metadata
- Source: user_instruction
- Related Files: ~/.clawteam/templates/dev-team.toml
- Tags: clawteam, team-structure, qc, devops
- Pattern-Key: orchestration.dev_team_with_qc_devops
- Recurrence-Count: 1
- First-Seen: 2026-04-06

---
## New Learnings — 2026-04-03 (ClawTeam Deep Dive)

### [LRN-20260403-001] no_sessions_spawn_for_multi_agent

**Logged**: 2026-04-03T09:30:00Z
**Priority**: critical
**Status**: resolved
**Area**: orchestration

### Summary
NEVER use sessions_spawn for multi-agent coordination. ALWAYS use clawteam CLI.

### Suggested Action
- Never call sessions_spawn for multi-agent work
- If used by mistake → immediately kill and redo with clawteam

### Metadata
- Source: user_correction
- Related Files: AGENTS.md, RULES.md
- Tags: clawteam, orchestration, sessions_spawn
- Pattern-Key: clawteam.no_subagent
- Recurrence-Count: 3
- First-Seen: 2026-04-03

---
### [LRN-20260406-003] strict_quality_gate_and_template_usage

**Logged**: 2026-04-06T08:04:00Z
**Priority**: critical
**Status**: resolved
**Area**: orchestration

### Summary
PM must enforce strict quality standards using templates and zero-tolerance policy; all teams must use templates from ~/.clawteam/templates/.

### Details
User explicitly required: khi review code thì phải cực kỳ khắt khe, phải đạt mọi tiêu chuẩn cao, không để tasks/projects không đạt chất lượng. Added comprehensive strict quality checklist to RULES.md and enhanced AGENTS.md with enforcement note. Also ensured dev and QC team templates use PM role and include QC/DevOps.

### Suggested Action
- PMs must verify all tasks independently (read diff, run tests, check coverage)
- Use the strict checklist; reject any non-compliance
- Always check templates directory when creating teams
- No task may complete unless ALL criteria passed

### Metadata
- Source: user_instruction
- Related Files: RULES.md, AGENTS.md, ~/.clawteam/templates/dev-team.toml, ~/.clawteam/templates/qc-team.toml
- Tags: quality, strict, template, review
- Pattern-Key: orchestration.strict_quality_gate
- Recurrence-Count: 1
- First-Seen: 2026-04-06
- Last-Seen: 2026-04-06
---

---

## [LRN-20260406-001] clawteam_spawn_method

**Logged**: 2026-04-06T10:10:00Z
**Priority**: critical
**Status**: resolved
**Area**: orchestration

### Summary
**Never use subprocess for spawning agents.** Always use `clawteam spawn tmux openclaw --team <team> --agent-name <name> --agent-type <type> --task "<task>"`.

### Details
When spawning ClawTeam agents, using `clawteam spawn subprocess openclaw` causes agents to die immediately after the subprocess shell exits. This resulted in:
- All 12 agents spawning but dying instantly
- 75 tasks all remaining `pending` with 0 `in_progress` because no one was alive to work
- Tasks falsely marked `completed` (only directory copying happened, not actual development)
- Zero dependency tracking (all tasks independent despite clear ordering requirements)
- Complete project management failure

### Suggested Action
- **ALWAYS** use `clawteam spawn tmux openclaw --team <team> --agent-name <name> ...` for persistent agent sessions
- **NEVER** use `clawteam spawn subprocess` — it exits immediately after the shell terminates
- Verify agents are alive: `tmux list-sessions | grep clawteam`
- Check task progress: `clawteam task list <team> --status in_progress`
- Set task dependencies with `clawteam task update <team> <id> --add-blocked-by <dep-id>`
- Monitor progress: `clawteam board attach <team>`

### Metadata
- Source: error
- Tags: clawteam, spawn, subprocess, orchestration, critical
### Metadata
- Source: error
- Tags: clawteam, spawn, subprocess, orchestration, critical
- Pattern-Key: clawteam.spawn_method
- Recurrence-Count: 1
- First-Seen: 2026-04-06
- Last-Seen: 2026-04-06

---

## [LRN-20260407-001] continuous_clawteam_monitoring_and_quality_control

**Logged**: 2026-04-07T07:07:00Z
**Priority**: critical
**Status**: in_progress
**Area**: orchestration/quality-control

### Summary
Continuous monitoring of ClawTeam progress and quality gates is mandatory to catch issues early and maintain consistent high-quality output.

### Details
User instruction: When ClawTeam is running, I must continuously monitor progress and check for specific quality control issues:

**Task Status Issues**:
- Blocked tasks that are not unblocked (stuck indefinitely)
- Tasks stuck in `pending` without moving to `in_progress`
- Tasks marked `in_progress` but not actually working (agents idle or unresponsive)
- Tasks not blocked but still pending (missing dependencies or abandoned)

**Agent Interaction & Review Issues**:
- Agents not communicating with each other (lack of inbox usage)
- Agents not doing self-review before reporting completion
- Agents not doing peer review (skipping peer feedback stage)
- Project manager not reviewing tasks (bypassing Tier 3 quality gate)

This is a **proactive oversight** requirement, not a reactive one. We must regularly check (multiple times per day during active team operations) to catch these issues before they cascade. The goal is to ensure consistent quality and prevent substandard work from completing.

### Suggested Action
Establish a monitoring cadence and checklist for active ClawTeam projects:

1. **Regular Check Schedule**
   - Check team boards every 2-4 hours during active work periods
   - More frequent (hourly) for tight deadlines / high-velocity teams
   - Less frequent (twice daily) for low-velocity / planning phases

2. **Monitoring Checklist**
   - Review board: identify any `blocked` tasks not recently unblocked
   - Check `pending` tasks: are old tasks stuck? Verify dependencies are set correctly
   - Check `in_progress` tasks: are agents actually active? Use `clawteam context log` to see recent activity
   - Verify inbox flow: are agents sending/receiving messages? Look for unanswered messages
   - Review task transitions: ensure `completed` tasks went through `needs-self-review` → `needs-peer-review` → `needs-leader-review`
   - Spot-check code: for tasks marked `completed`, verify worker did self-review, peer review occurred, and leader approval given

3. **Automation/Aids**
   - Create a script or alias to run quick checks: `clawteam board show <team>` + `clawteam task list <team> --status blocked` + `clawteam task list <team> --status in_progress`
   - Set reminders during active development sprints
   - Use `clawteam context conflicts` to detect worktree issues

4. **Intervention Protocol**
   - If an agent is idle (`in_progress` but no activity for >2h), send inbox message to check status
   - If blocked task not unblocked, contact PM/leader to resolve
   - If reviews skipped, request immediate self/peer review before allowing task to advance
   - Document recurring issues in learnings to improve agent prompts/team setup

### Metadata
- Source: user_instruction
- Tags: clawteam, monitoring, quality-gate, recurring-check, orchestration
- Pattern-Key: orchestration.continuous_monitoring
- Recurrence-Count: ongoing (recurring check)
- First-Seen: 2026-04-07
- Last-Seen: 2026-04-07

---