Next Actions Directory

Purpose

This directory contains ACTIONABLE items that still need work. These are not documentation or historical records - they are living task lists that guide ongoing development.

Use this for:

• Feature implementations in progress
• Known bugs/issues that need fixing
• Technical debt that needs addressing
• Refactoring tasks with clear scope
• Security/performance improvements planned

Do NOT use this for:

• Completed work (use git history)
• General ideas (use GitHub Discussions/Issues)
• Documentation (use /docs/)
• Progress reports (use .tmp/ directory)

File Naming Convention

YYYY-MM-DD-feature-name.md

Examples:

• 2025-12-19-auth-migration.md
• 2025-12-20-voice-call-improvements.md
• 2025-12-15-database-optimization.md

Delete files when all items are complete.

Template Format

Each next-actions file should follow this structure:

# [Feature/Area Name] - Next Actions

**Created:** YYYY-MM-DD
**Owner:** @username (optional)
**Priority:** High | Medium | Low
**Status:** In Progress | Blocked | Planning

## Context

Brief 2-3 sentence explanation of what this is about and why it matters.

**Related:**
- PR: #123
- Issue: #456
- Code: `/path/to/relevant/file.ts`
- Docs: `/docs/relevant-doc.md`

## Action Items

### High Priority

- [ ] **[ACTION-001]** Clear, specific task description
  - **Owner:** @username (optional)
  - **Effort:** Small | Medium | Large
  - **Blocked by:** Nothing | Issue #123 | Other dependency
  - **Notes:** Any important context or considerations

- [ ] **[ACTION-002]** Another task
  - **Owner:** @username
  - **Effort:** Medium
  - **Blocked by:** ACTION-001
  - **Notes:** Depends on completion of ACTION-001

### Medium Priority

- [ ] **[ACTION-003]** Task description
  - **Owner:** Unassigned
  - **Effort:** Small
  - **Blocked by:** Nothing

### Completed

- [x] **[ACTION-000]** Example completed task (YYYY-MM-DD)
  - **Owner:** @username
  - **Result:** What was accomplished, link to PR #123

## Notes

Any additional context, decisions made, or important considerations.

## Success Criteria

Clear definition of when this next-actions file can be deleted:
- [ ] All high priority items complete
- [ ] All medium priority items complete or converted to GitHub issues
- [ ] Related PRs merged
- [ ] Documentation updated

Priority Definitions

Priority	Definition	Timeline
High	Blocks other work, affects critical paths, or security/data integrity issues	This week
Medium	Important but not blocking, tech debt, performance improvements	This month
Low	Nice to have, minor improvements, cleanup	This quarter

Effort Estimates

Effort	Definition	Time
Small	Simple change, single file, low risk	< 2 hours
Medium	Multiple files, some complexity, moderate risk	2-8 hours
Large	Complex change, many files, high risk, needs design	> 8 hours

Workflow

Creating a Next-Actions File

1. Use the template above
2. Fill in context and action items
3. Link to related code/PRs/issues
4. Commit to git (these ARE tracked)

Updating a Next-Actions File

1. Check off completed items - move to "Completed" section
2. Add new items as they're discovered
3. Update blocked status as dependencies resolve
4. Commit changes regularly

Closing a Next-Actions File

When ALL items are complete or converted to GitHub issues:

1. Ensure all checkboxes are checked or items are moved elsewhere
2. Delete the file: git rm docs/next-actions/YYYY-MM-DD-feature-name.md
3. Commit: git commit -m "chore: close next-actions for [feature] - all items complete"

Best Practices

DO:

• Keep items specific and actionable ("Add validation to X" not "Improve X")
• Link to relevant code, PRs, and issues
• Update status as you work
• Delete files when complete
• Use effort/priority to guide work order
• Break large tasks into smaller actionable items

DON'T:

• Create next-actions files for vague ideas
• Let completed files sit around (delete them)
• Duplicate GitHub issues here (link to them instead)
• Write essays (keep it concise and actionable)
• Use this for documentation (use /docs/ or /features/)

Examples

Good Next-Actions Items

• [ACTION-001] Add email validation to signup form in /app/api/auth/signup/route.ts
• [ACTION-002] Fix race condition in voice call webhook handler (Issue #456)
• [ACTION-003] Migrate Prisma queries in /lib/services/lead/ to use batch operations

Bad Next-Actions Items

• Make the app better (too vague)
• Fix all bugs (not specific)
• Research AI stuff (not actionable - use GitHub Discussions)
• Document the codebase (not an action item - use /docs/)

Integration with Other Systems

System	Relationship	When to Use
GitHub Issues	Track public bugs/features	User-facing issues, community requests
GitHub PRs	Implement action items	When ready to code, link back to next-actions
/docs/	Permanent documentation	Architecture, guides, runbooks
.tmp/	Temporary work	Analysis, verification, one-time reports
Git commits	History of changes	What was done and why
Next-Actions	Immediate work queue	What needs to be done next

Maintenance

Weekly:

• Review all next-actions files
• Update progress on action items
• Delete completed files
• Re-prioritize as needed

Monthly:

• Convert low-priority items to GitHub issues if not urgent
• Archive or delete stale next-actions files
• Ensure all files have recent activity or clear blockers

Questions?

If you're unsure whether something belongs in next-actions:

Ask yourself:

1. Is this actionable RIGHT NOW? (Yes - next-actions, No - GitHub issue)
2. Is someone actively working on this? (Yes - next-actions, No - GitHub issue)
3. Does this have a clear completion criteria? (Yes - next-actions, No - refine it first)

If still unsure, default to GitHub Issues and link to them from a next-actions file if needed.