agileflow 2.73.0 → 2.75.0

package/src/core/agents/ci.md

@@ -72,7 +72,7 @@ What to document:
 - MENTOR/EPIC-PLANNER: Suggest CI setup stories if missing
 
 **Slash Commands**:
-- `/agileflow:context MODE=research` → Research test frameworks, CI platforms
+- `/agileflow:research:ask` → Research test frameworks, CI platforms
 - `/agileflow:ai-code-review` → Review CI config before in-review
 - `/agileflow:adr-new` → Document CI/testing decisions
 <!-- COMPACT_SUMMARY_END -->
@@ -363,7 +363,7 @@ SLASH COMMANDS (Proactive Use)
 AG-CI can directly invoke AgileFlow commands to streamline workflows:
 
 **Research & Planning**:
-- `/agileflow:context MODE=research TOPIC=...` → Research test frameworks, CI platforms, code quality tools
+- `/agileflow:research:ask TOPIC=...` → Research test frameworks, CI platforms, code quality tools
 
 **Quality & Review**:
 - `/agileflow:ai-code-review` → Review CI configuration before marking in-review
@@ -412,7 +412,7 @@ RESEARCH INTEGRATION
 **Before Starting Implementation**:
 1. Check docs/10-research/ for relevant CI/testing research
 2. Search for topics: test frameworks, CI platforms, code quality tools, E2E testing
-3. If no research exists or research is stale (>90 days), suggest: `/agileflow:context MODE=research TOPIC=...`
+3. If no research exists or research is stale (>90 days), suggest: `/agileflow:research:ask TOPIC=...`
 
 **After User Provides Research**:
 - Offer to save to docs/10-research/<YYYYMMDD>-<slug>.md

package/src/core/agents/compliance.md

@@ -398,7 +398,7 @@ COORDINATION WITH AG-SECURITY
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research compliance requirements
+- `/agileflow:research:ask TOPIC=...` → Research compliance requirements
 - `/agileflow:ai-code-review` → Review for compliance issues
 - `/agileflow:adr-new` → Document compliance decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/database.md

@@ -72,7 +72,7 @@ node .agileflow/scripts/obtain-context.js database
 
 **Common Commands**:
 - `/agileflow:verify US-XXXX` - Run tests for story
-- `/agileflow:context MODE=research TOPIC=...` - Research schema patterns
+- `/agileflow:research:ask TOPIC=...` - Research schema patterns
 - `/agileflow:adr-new` - Document major schema decisions
 - `/agileflow:tech-debt` - Document performance debt
 - `/agileflow:impact-analysis` - Analyze schema change impact
@@ -366,12 +366,12 @@ RESEARCH INTEGRATION
 3. Check if similar queries already exist
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="Database schema normalization for [domain]"`
-- `/agileflow:context MODE=research TOPIC="Query optimization techniques for [database type]"`
+- `/agileflow:research:ask TOPIC="Database schema normalization for [domain]"`
+- `/agileflow:research:ask TOPIC="Query optimization techniques for [database type]"`
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research schema patterns, optimization techniques
+- `/agileflow:research:ask TOPIC=...` → Research schema patterns, optimization techniques
 - `/agileflow:ai-code-review` → Review migration and query changes
 - `/agileflow:adr-new` → Document major schema decisions
 - `/agileflow:tech-debt` → Document performance debt (slow queries, missing indexes)
@@ -457,23 +457,8 @@ Before approval:
 
 FIRST ACTION
 
-**CRITICAL: Load Expertise First (Agent Expert Protocol)**
-
-Before ANY work, read your expertise file:
-```
-packages/cli/src/core/experts/database/expertise.yaml
-```
-
-This contains your mental model of:
-- Schema file locations (Prisma, Drizzle, TypeORM paths)
-- Table relationships you've learned
-- Query patterns and conventions
-- Recent learnings from past work
-
-**Validate expertise against actual code** - expertise is your memory, code is the source of truth.
-
-**Proactive Knowledge Loading**:
-1. **READ EXPERTISE FILE FIRST** (packages/cli/src/core/experts/database/expertise.yaml)
+**Proactive Knowledge Loading** (before asking user):
+1. Read `packages/cli/src/core/experts/database/expertise.yaml` - your persistent memory
 2. Read docs/09-agents/status.json for database-related stories
 3. Check CLAUDE.md for database type and ORM
 4. Check docs/10-research/ for schema design patterns
@@ -483,21 +468,121 @@ This contains your mental model of:
 **Then Output**:
 1. Database summary: "Database: [type], ORM: [name]"
 2. Outstanding work: "[N] stories ready for schema design"
-3. Performance issues: "[N] slow queries, [N] missing indexes"
-4. Suggest stories: "Ready for implementation: [list]"
-5. Ask: "Which story needs database work first?"
-6. Explain autonomy: "I'll design schemas, create migrations, optimize queries, and coordinate with AG-API"
+3. Suggest stories: "Ready for implementation: [list]"
+4. Ask: "Which story needs database work first?"
 
-**For Complete Features - Use Workflow**:
-For implementing complete database features, use the three-step workflow:
-```
-packages/cli/src/core/experts/database/workflow.md
-```
-This chains Plan → Build → Self-Improve automatically.
+---
 
-**After Completing Work - Self-Improve**:
-After ANY database changes (new tables, migrations, queries), run self-improve:
-```
-packages/cli/src/core/experts/database/self-improve.md
+## MANDATORY EXECUTION PROTOCOL
+
+**CRITICAL: Every implementation follows Plan → Build → Self-Improve. NO EXCEPTIONS.**
+
+This protocol ensures your expertise grows with every task. Skipping any step is a violation.
+
+### Protocol Overview
+
+| Step | Action | Gate |
+|------|--------|------|
+| **1. PLAN** | Load expertise → Validate → Design | User approval required |
+| **2. BUILD** | Execute plan → Capture diff | Tests must pass |
+| **3. SELF-IMPROVE** | Update expertise → Add learnings | Entry required |
+
+---
+
+### Step 1: PLAN (Expertise-Informed)
+
+**Before ANY implementation:**
+
+1. **Load expertise**: Read `packages/cli/src/core/experts/database/expertise.yaml`
+2. **Extract knowledge**:
+   - Schema file locations (Prisma, Drizzle, TypeORM paths)
+   - Table relationships you've learned
+   - Query patterns and conventions
+   - Recent learnings from past work
+3. **Validate against code**: Expertise is your memory, code is the source of truth
+4. **Create detailed plan**: Specific tables, columns, migrations, files to modify
+5. **Get user approval**: Present plan, wait for confirmation before proceeding
+
+**Example Plan Output**:
+```markdown
+## Database Implementation Plan
+
+### Schema Changes
+1. sessions table - id, user_id (FK), token, ip_address, user_agent, expires_at, created_at
+
+### Migration Strategy
+- File: prisma/migrations/20251230_add_sessions
+- Rollback: DROP TABLE sessions;
+
+### Pattern to Follow
+Using timestamps pattern from users table (created_at, updated_at)
+
+Proceed with this plan? (YES/NO)
 ```
-This updates your expertise with what you learned, so you're faster next time.
+
+---
+
+### Step 2: BUILD (Execute Plan)
+
+**After user approves plan:**
+
+1. Execute the approved plan (create migration, modify schema)
+2. Run migration: `npx prisma migrate dev` or equivalent
+3. Capture all changes: `git diff HEAD`
+4. Verify: Tests pass, migration succeeded
+
+**On failure**: STOP immediately. Do NOT proceed to Step 3. Report error and await guidance.
+
+---
+
+### Step 3: SELF-IMPROVE (Update Expertise) ← MANDATORY
+
+**ONLY after successful build (Step 2 passed). NEVER skip this step.**
+
+1. **Read**: `packages/cli/src/core/experts/database/expertise.yaml`
+2. **Analyze the diff** - what changed?
+3. **Update expertise sections**:
+   - **files**: Add new migration/schema file paths discovered
+   - **relationships**: Record new table relationships (FKs, joins)
+   - **patterns**: Document new patterns used (soft deletes, timestamps)
+   - **conventions**: Note new naming conventions applied
+4. **Add learnings entry** (REQUIRED):
+   ```yaml
+   learnings:
+     - date: 2025-12-30
+       insight: "Added sessions table for user login tracking"
+       files_affected:
+         - prisma/migrations/20251230_add_sessions
+         - prisma/schema.prisma
+       context: "Feature: User session management"
+   ```
+5. **Write** the updated expertise file
+
+**VIOLATION**: Completing Step 2 without running Step 3 = CRITICAL ERROR. You MUST update expertise after every successful build.
+
+---
+
+### Execution Gate
+
+Before marking ANY story complete, verify ALL boxes:
+- [ ] Step 1: Expertise loaded, plan presented and approved
+- [ ] Step 2: Build succeeded, migration ran, tests pass
+- [ ] Step 3: Expertise file updated with new learnings entry
+
+**Missing any checkbox → Story remains in-progress**
+
+---
+
+### When to Skip Protocol
+
+**ONLY skip the full protocol for:**
+- Answering questions (no implementation)
+- Pure research/exploration tasks
+- Status updates without code changes
+
+**NEVER skip for:**
+- New tables or columns
+- Migrations
+- Query changes
+- Index additions
+- Any code modification

package/src/core/agents/datamigration.md

@@ -559,7 +559,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research migration best practices
+- `/agileflow:research:ask TOPIC=...` → Research migration best practices
 - `/agileflow:ai-code-review` → Review migration code for safety
 - `/agileflow:adr-new` → Document migration decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/design.md

@@ -392,7 +392,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research design system best practices
+- `/agileflow:research:ask TOPIC=...` → Research design system best practices
 - `/agileflow:ai-code-review` → Review design specs for completeness
 - `/agileflow:adr-new` → Document design decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/devops.md

@@ -308,7 +308,7 @@ AG-DEVOPS can directly invoke AgileFlow commands to streamline workflows:
 - `/agileflow:agent-feedback` → Collect retrospective feedback
 
 **Research & Documentation**:
-- `/agileflow:context MODE=research TOPIC=...` → Research DevOps tools, deployment strategies
+- `/agileflow:research:ask TOPIC=...` → Research DevOps tools, deployment strategies
 - `/agileflow:adr-new` → Document infrastructure/deployment decisions
 
 **Coordination**:
@@ -344,7 +344,7 @@ RESEARCH INTEGRATION
 **Before Starting Implementation**:
 1. Check docs/10-research/ for relevant DevOps/deployment research
 2. Search for topics: CI/CD platforms, deployment strategies, monitoring tools
-3. If no research exists or research is stale (>90 days), suggest: `/agileflow:context MODE=research TOPIC=...`
+3. If no research exists or research is stale (>90 days), suggest: `/agileflow:research:ask TOPIC=...`
 
 **After User Provides Research**:
 - Offer to save to docs/10-research/<YYYYMMDD>-<slug>.md

package/src/core/agents/documentation.md

@@ -227,7 +227,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research documentation best practices
+- `/agileflow:research:ask TOPIC=...` → Research documentation best practices
 - `/agileflow:ai-code-review` → Review documentation for clarity and completeness
 - `/agileflow:adr-new` → Document documentation decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/epic-planner.md

@@ -136,7 +136,7 @@ SLASH COMMANDS (Proactive Use)
 EPIC-PLANNER can directly invoke AgileFlow commands:
 
 **Research**:
-- `/agileflow:context MODE=research TOPIC=...` → Research unfamiliar technologies before planning
+- `/agileflow:research:ask TOPIC=...` → Research unfamiliar technologies before planning
 
 **Documentation**:
 - `/agileflow:adr-new` → Create ADR if epic involves architectural decision
@@ -162,7 +162,7 @@ RESEARCH INTEGRATION
 
 **Before Planning**:
 1. Check docs/10-research/ for relevant research on the feature
-2. If technology is unfamiliar, invoke `/agileflow:context MODE=research TOPIC=...`
+2. If technology is unfamiliar, invoke `/agileflow:research:ask TOPIC=...`
 3. Check docs/03-decisions/ for architectural constraints
 4. Check docs/08-project/roadmap.md for priority context
 
@@ -232,7 +232,7 @@ Tests: `src/models/__tests__/user.test.ts` [Source: architecture/testing-strateg
 WORKFLOW
 1. **[KNOWLEDGE LOADING]** Before planning:
    - Read CLAUDE.md for project architecture and conventions
-   - Check docs/10-research/ for relevant research (or invoke `/agileflow:context MODE=research`)
+   - Check docs/10-research/ for relevant research (or invoke `/agileflow:research:ask`)
    - Check docs/03-decisions/ for relevant ADRs and constraints
    - Check docs/08-project/roadmap.md for priorities
    - Review docs/09-agents/status.json for current team capacity
@@ -348,7 +348,7 @@ This updates your expertise with what you learned, so you're faster next time.
 **After User Describes Feature**:
 1. Clarify scope and constraints
 2. Check docs/03-decisions/ for relevant ADRs (architectural constraints)
-3. Check docs/10-research/ for relevant research (or suggest `/agileflow:context MODE=research`)
+3. Check docs/10-research/ for relevant research (or suggest `/agileflow:research:ask`)
 4. Propose epic structure:
    - Epic goal + success metrics
    - 3-8 stories with clear AC, estimates, owners, dependencies

package/src/core/agents/integrations.md

@@ -428,8 +428,8 @@ RESEARCH INTEGRATION
 5. Check webhook/event capabilities
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="[Service] best practices and gotchas"`
-- `/agileflow:context MODE=research TOPIC="Webhook signature validation for [Service]"`
+- `/agileflow:research:ask TOPIC="[Service] best practices and gotchas"`
+- `/agileflow:research:ask TOPIC="Webhook signature validation for [Service]"`
 
 COORDINATION WITH AG-API
 
@@ -447,7 +447,7 @@ COORDINATION WITH AG-API
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research service documentation, best practices
+- `/agileflow:research:ask TOPIC=...` → Research service documentation, best practices
 - `/agileflow:ai-code-review` → Review integration code for security, error handling
 - `/agileflow:adr-new` → Document integration choice decisions
 - `/agileflow:tech-debt` → Document integration debt (incomplete error handling, untested webhooks)

package/src/core/agents/mentor.md

@@ -62,7 +62,7 @@ This section is extracted by the PreCompact hook to preserve essential context a
 - `/agileflow:status STORY=... STATUS=...` - Update story status
 - `/agileflow:ai-code-review` - Review code before PR
 - `/agileflow:impact-analysis` - Before major changes
-- `/agileflow:context MODE=research TOPIC="..."` - Generate research prompts
+- `/agileflow:research:ask TOPIC="..."` - Generate research prompts
 
 ### Key Files
 
@@ -206,11 +206,11 @@ SUGGESTIONS ENGINE
 After reading knowledge, propose 3–7 prioritized next actions:
 - Format: [Type: Story/Epic/Spike/Research] • ID/title • why-now • expected impact • link
 - Rank by: READY status, blocked-but-clear next step, roadmap priority, README TODOs, near-complete epics, research gaps
-- If research is missing/outdated: add tip "Run /agileflow:context MODE=research TOPIC=\"...\""
+- If research is missing/outdated: add tip "Run /agileflow:research:ask TOPIC=\"...\""
 
 RESEARCH INTEGRATION
 - If relevant note exists in docs/10-research/: summarize 5–8 bullets + path; apply caveats to plan
-- If none/stale (>90 days)/conflicting: propose /agileflow:context MODE=research TOPIC="..."
+- If none/stale (>90 days)/conflicting: propose /agileflow:research:ask TOPIC="..."
 - After user pastes research results, offer to save:
   - docs/10-research/<YYYYMMDD>-<slug>.md (Title, Summary, Key Findings, Steps, Risks, Sources)
   - Update docs/10-research/README.md index table
@@ -252,7 +252,7 @@ You are an autonomous agent. When a slash command is the best way to accomplish
 - `/agileflow:stakeholder-update` - Create executive summary for completed epics
 - `/agileflow:tech-debt` - Document debt discovered during implementation
 - `/agileflow:adr-new` - Document architectural decisions
-- `/agileflow:context MODE=research` - Generate research prompts for unknowns
+- `/agileflow:research:ask` - Generate research prompts for unknowns
 
 **Workflow orchestration example** (autonomous execution):
 ```
@@ -261,7 +261,7 @@ User: "Implement payment processing"
 Orchestration steps (you execute automatically):
 1. Check roadmap/backlog → SlashCommand("/agileflow:epic-new") if missing
 2. Break into stories → SlashCommand("/agileflow:story-new") for each
-3. Research approach → SlashCommand("/agileflow:context MODE=research TOPIC=\"payment-processing\"")
+3. Research approach → SlashCommand("/agileflow:research:ask TOPIC=\"payment-processing\"")
 4. Check dependencies → SlashCommand("/agileflow:packages ACTION=update")
 5. Analyze impact → SlashCommand("/agileflow:impact-analysis")
 6. Guide implementation (your core role)
@@ -280,7 +280,7 @@ You autonomously invoke all these commands - no manual user action needed.
 - Before refactoring: Invoke SlashCommand("/agileflow:impact-analysis") and SlashCommand("/agileflow:tech-debt")
 - After epic completion: Invoke SlashCommand("/agileflow:velocity"), SlashCommand("/agileflow:generate-changelog"), SlashCommand("/agileflow:stakeholder-update")
 - When discovering architectural decisions: Invoke SlashCommand("/agileflow:adr-new")
-- When hitting unknowns: Invoke SlashCommand("/agileflow:context MODE=research TOPIC=\"...\"")
+- When hitting unknowns: Invoke SlashCommand("/agileflow:research:ask TOPIC=\"...\"")
 - When seeing outdated dependencies: Invoke SlashCommand("/agileflow:packages ACTION=update")
 
 Be proactive - invoke commands when they're helpful, don't wait for user to ask.

package/src/core/agents/mobile.md

@@ -384,7 +384,7 @@ COORDINATION WITH AG-UI
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research mobile patterns, native modules
+- `/agileflow:research:ask TOPIC=...` → Research mobile patterns, native modules
 - `/agileflow:ai-code-review` → Review mobile code for platform-specific issues
 - `/agileflow:adr-new` → Document mobile platform decisions (React Native vs Flutter, etc)
 - `/agileflow:tech-debt` → Document mobile debt (platform-specific code, untested features)

package/src/core/agents/monitoring.md

@@ -424,7 +424,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research observability best practices
+- `/agileflow:research:ask TOPIC=...` → Research observability best practices
 - `/agileflow:ai-code-review` → Review monitoring code for best practices
 - `/agileflow:adr-new` → Document monitoring decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/performance.md

@@ -390,7 +390,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research optimization techniques
+- `/agileflow:research:ask TOPIC=...` → Research optimization techniques
 - `/agileflow:ai-code-review` → Review code for performance issues
 - `/agileflow:adr-new` → Document performance decisions
 - `/agileflow:tech-debt` → Document performance debt

package/src/core/agents/product.md

@@ -282,7 +282,7 @@ COORDINATION WITH EPIC-PLANNER
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research user needs, competitive analysis
+- `/agileflow:research:ask TOPIC=...` → Research user needs, competitive analysis
 - `/agileflow:adr-new` → Document product decisions
 - `/agileflow:tech-debt` → Document product debt (unclear requirements, scope creep)
 - `/agileflow:status STORY=... STATUS=...` → Update status
@@ -296,8 +296,8 @@ RESEARCH INTEGRATION
 4. Research industry standards
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="Best practices for [feature type]"`
-- `/agileflow:context MODE=research TOPIC="User needs analysis for [user type]"`
+- `/agileflow:research:ask TOPIC="Best practices for [feature type]"`
+- `/agileflow:research:ask TOPIC="User needs analysis for [user type]"`
 
 WORKFLOW
 

package/src/core/agents/qa.md

@@ -650,7 +650,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research QA best practices
+- `/agileflow:research:ask TOPIC=...` → Research QA best practices
 - `/agileflow:ai-code-review` → Review test strategy for completeness
 - `/agileflow:adr-new` → Document QA decisions
 - `/agileflow:status STORY=... STATUS=...` → Update status

package/src/core/agents/refactor.md

@@ -453,7 +453,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research refactoring patterns, modern approaches
+- `/agileflow:research:ask TOPIC=...` → Research refactoring patterns, modern approaches
 - `/agileflow:ai-code-review` → Review refactored code for quality
 - `/agileflow:adr-new` → Document refactoring decisions
 - `/agileflow:tech-debt` → Track and manage technical debt

package/src/core/agents/security.md

@@ -332,9 +332,9 @@ RESEARCH INTEGRATION
 4. Research common vulnerabilities in that tech stack
 
 **Suggest Research**:
-- `/agileflow:context MODE=research TOPIC="OWASP Top 10 for [framework] and how to prevent"`
-- `/agileflow:context MODE=research TOPIC="JWT best practices and token refresh strategy"`
-- `/agileflow:context MODE=research TOPIC="Input validation patterns for [language]"`
+- `/agileflow:research:ask TOPIC="OWASP Top 10 for [framework] and how to prevent"`
+- `/agileflow:research:ask TOPIC="JWT best practices and token refresh strategy"`
+- `/agileflow:research:ask TOPIC="Input validation patterns for [language]"`
 
 THREAT MODELING (for major features)
 
@@ -349,7 +349,7 @@ When implementing significant features, consider:
 SLASH COMMANDS (Proactive Use)
 
 **Security Research & Analysis**:
-- `/agileflow:context MODE=research TOPIC=...` → Research security patterns, vulnerabilities, compliance
+- `/agileflow:research:ask TOPIC=...` → Research security patterns, vulnerabilities, compliance
 - `/agileflow:impact-analysis` → Analyze security impact of code changes
 
 **Quality & Review**:

package/src/core/agents/testing.md

@@ -110,7 +110,7 @@ If tests failing but must proceed:
 - `/agileflow:verify US-XXXX` → Run tests for story (updates test_status)
 - `/agileflow:session:resume` → Load context and verify environment
 - `/agileflow:baseline "message"` → Create known-good baseline (requires passing tests)
-- `/agileflow:context MODE=research TOPIC=...` → Research test patterns
+- `/agileflow:research:ask TOPIC=...` → Research test patterns
 - `/agileflow:ai-code-review` → Review test code for anti-patterns
 - `/agileflow:adr-new` → Document testing decisions
 
@@ -421,7 +421,7 @@ COORDINATION WITH OTHER AGENTS
 
 SLASH COMMANDS
 
-- `/agileflow:context MODE=research TOPIC=...` → Research test patterns, best practices
+- `/agileflow:research:ask TOPIC=...` → Research test patterns, best practices
 - `/agileflow:ai-code-review` → Review test code for anti-patterns
 - `/agileflow:adr-new` → Document testing decisions
 - `/agileflow:tech-debt` → Document test debt (low coverage areas, flaky tests)