12 KiB
Learnings Log
This file captures corrections, knowledge gaps, and best practices discovered during agent operation.
Format
Each entry:
## [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:
- Each worker must self-review their completed work before any peer review.
- Other workers then review the code.
- 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/UIqc-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 criteriaqa-engineer— Test coverage, TDD compliance, edge case validation, regression testsdevops-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