AI Workflow

The Four AI Spaces

BackMark provides four dedicated spaces where your AI assistant can work autonomously while maintaining complete transparency and documentation.

1. `ai_plan`

Purpose: Implementation strategy and architecture

When: Before starting work

Content: Steps, files, dependencies, technical approach

2. `ai_notes`

Purpose: Real-time development log

When: During implementation

Content: Progress, decisions, issues, solutions (timestamped)

3. `ai_documentation`

Purpose: End-user and developer docs

When: As features are built

Content: API docs, usage examples, configuration

4. `ai_review`

Purpose: Self-review and quality checks

When: Before marking complete

Content: Completeness checklist, metrics, questions

📋 ai_plan - Implementation Planning

What Goes in ai_plan?

✅ Implementation steps - Ordered list of what to build
✅ Files to create/modify - Complete file list with purpose
✅ Dependencies - Libraries, tools, services needed
✅ Technical approach - Architecture decisions and patterns
✅ Potential challenges - Known risks and mitigation strategies

Command:

backmark task ai-plan <task-id> "Plan content in Markdown"

Example:

$ backmark task ai-plan 42 "## Implementation Steps 1. **Setup Fuse.js library** - Install: \`npm install fuse.js\` - Configure search options (threshold, keys) 2. **Create search utility** - File: src/utils/fuzzy-search.js - Wrapper around Fuse.js with project-specific config 3. **Integrate into task list command** - Modify: src/commands/task/list.js - Add --search flag 4. **Add tests** - File: tests/fuzzy-search.test.js - Test accuracy, performance, edge cases ## Files to Create/Modify - \`src/utils/fuzzy-search.js\` (new) - Search utility - \`src/commands/task/list.js\` (modify) - Integration - \`tests/fuzzy-search.test.js\` (new) - Tests - \`package.json\` (modify) - Add dependency ## Dependencies - fuse.js@^7.0.0 ## Technical Approach Using Fuse.js for fuzzy search because: - Mature, well-tested library - Configurable threshold - Works with complex objects - No additional dependencies Search will index: title, description, labels, assignees ## Potential Challenges - Performance with 1000+ tasks → Mitigate with LokiJS indexing - Search relevance tuning → Start with threshold 0.3, adjust based on usage"

✓ Added AI plan to task #42

📝 ai_notes - Development Log

What Goes in ai_notes?

✅ Timestamped entries - When each step was completed
✅ Progress updates - What was accomplished
✅ Decisions made - Choices and reasoning
✅ Problems encountered - Issues that arose
✅ Solutions applied - How problems were resolved
✅ Deviations from plan - Changes to original approach

Command:

backmark task ai-note <task-id> "Note content with timestamp"

Example:

$ backmark task ai-note 42 "**2024-11-06 10:00** - Installed fuse.js Successfully added to package.json and ran npm install. Version: 7.0.0 **2024-11-06 10:30** - Created fuzzy-search utility Implemented in src/utils/fuzzy-search.js Configuration: threshold 0.3, searches title/description/labels **2024-11-06 11:00** - Integrated into task list Added --search flag to task list command Works as expected in manual testing **2024-11-06 11:30** - Issue: Performance degradation Search taking ~500ms with 500+ tasks Solution: Added caching layer, now ~20ms average **2024-11-06 12:00** - Tests complete Added 8 test cases, all passing Coverage: 95% of search utility"

✓ Added AI note to task #42

Pro Tip: Always include timestamps for better context recovery.

📚 ai_documentation - User Documentation

What Goes in ai_documentation?

✅ API documentation - Function signatures, parameters, returns
✅ Usage examples - Real code examples
✅ Configuration options - Available settings
✅ Integration guides - How to use with existing code
✅ Troubleshooting - Common issues and solutions

Command:

backmark task ai-doc <task-id> "Documentation in Markdown"

Example:

$ backmark task ai-doc 42 "## Fuzzy Search Feature ### Usage Search tasks by any keyword: \`\`\`bash backmark task list --search \"authentication\" \`\`\` ### How it Works Fuzzy search indexes: - Task title - Task description - Labels - Assignees ### Configuration Adjust search threshold in config.yml: \`\`\`yaml search: threshold: 0.3 # Lower = stricter (0.0-1.0) maxResults: 50 \`\`\` ### Examples \`\`\`bash # Find all auth-related tasks backmark task list --search \"auth\" # Combine with filters backmark task list --search \"api\" --status \"In Progress\" \`\`\` ### Performance - Average query time: ~20ms - Handles 1000+ tasks efficiently - Results cached automatically"

✓ Added AI documentation to task #42

✅ ai_review - Self-Review

What Goes in ai_review?

✅ Completeness checklist - All requirements met
✅ Tests performed - What was tested and results
✅ Quality metrics - Coverage, performance, etc.
✅ Code quality - Standards followed, refactorings done
✅ Documentation status - What docs were created
✅ Known limitations - Current constraints
✅ Questions for human - Items needing validation

Command:

backmark task ai-review <task-id> "Review content"

Example:

$ backmark task ai-review 42 "## Self Review ### Completeness Checklist ✅ Fuse.js integration complete ✅ Search command working ✅ Tests written and passing ✅ Documentation complete ✅ Performance optimized ### Tests Performed - Unit tests: 8/8 passing - Integration tests: 3/3 passing - Manual testing: Verified with 500+ task dataset - Edge cases: Empty queries, special characters - all handled ### Quality Metrics - Test coverage: 95% - Average search time: 20ms - Memory usage: +2MB (acceptable) - No new dependencies beyond fuse.js ### Code Quality - ESLint: No warnings - TypeScript: No type errors - Followed project conventions - Added JSDoc comments ### Documentation ✅ API documentation complete ✅ Usage examples provided ✅ Configuration documented ✅ Troubleshooting section added ### Known Limitations - Search threshold not auto-tuned (manual config) - Multi-language support not implemented (future enhancement) ### Questions for Human Review 1. Is the default threshold of 0.3 appropriate? 2. Should we add search result highlighting? 3. Any additional fields to index (e.g., milestone)? ### Recommendation Task is ready for completion. All acceptance criteria met."

✓ Added AI review to task #42

✅ Acceptance Criteria - Definition of Done

What Are Acceptance Criteria?

Acceptance criteria define the specific conditions that must be met for a task to be considered complete. They serve as a contract between human and AI, ensuring clear expectations and measurable outcomes.

Why Use Acceptance Criteria?

✅ Clear expectations - Both human and AI know what "done" means
✅ Quality assurance - Prevent incomplete implementations
✅ Trackable progress - Check off items as you go
✅ Validation gate - ai-review-ready verifies all criteria

Best Practices

✅ Be specific - "API returns 200 OK" not "API works"
✅ Make them testable - Each criterion should be verifiable
✅ Keep them atomic - One condition per criterion
✅ Add early - Define criteria before starting work

Managing Acceptance Criteria

Add Criteria:

$ backmark task add-criterion 42 "Search returns results in under 100ms"

✓ Criterion added: "Search returns results in under 100ms"

$ backmark task add-criterion 42 "Fuzzy matching works with typos"

✓ Criterion added: "Fuzzy matching works with typos"

$ backmark task add-criterion 42 "All unit tests pass"

✓ Criterion added: "All unit tests pass"

Check Off Completed Criteria:

$ backmark task check 42 0

✓ Checked criterion [0]: "Search returns results in under 100ms"

$ backmark task check 42 1

✓ Checked criterion [1]: "Fuzzy matching works with typos"

Note: Criteria are 0-indexed. Use backmark task view 42 to see all criteria with their indices.

Integration with AI Workflow

Acceptance criteria integrate seamlessly with the AI workflow:

1. In AI Plan

Reference criteria when planning implementation:

## Plan
Based on acceptance criteria:
- [0] Search under 100ms → Use caching
- [1] Fuzzy matching → Implement Fuse.js
- [2] Tests pass → Write unit tests first

2. In AI Review

Verify each criterion in your self-review:

## Acceptance Criteria Status
✅ [0] Search under 100ms - Avg 20ms
✅ [1] Fuzzy matching - Works with 2 typos
✅ [2] Tests pass - 8/8 passing

3. Validation Before Closing:

$ backmark task ai-review-ready 42

🔍 Checking task #42 readiness...

✅ All subtasks completed

✅ No blockers

✅ All dependencies resolved

✅ All acceptance criteria checked (3/3)

✅ AI review present

✓ Task #42 is ready to be closed!

Important: If acceptance criteria are not all checked, ai-review-ready will warn you and the task cannot be closed (unless forced).

🤖 AI Automation Features

BackMark includes intelligent automation to streamline your workflow:

`ai-breakdown`

Automatically decompose complex tasks into logical subtasks with dependencies.

backmark task ai-breakdown 42

Analyzes task description and creates subtasks based on implementation patterns, technical keywords, and common workflows.

`ai-estimate`

Estimate task complexity, duration, and risks using heuristic analysis.

backmark task ai-estimate 42

Provides complexity rating (low/medium/high/critical), estimated duration, risk factors, and confidence level.

`ai-review-ready`

Validate task is ready to be marked complete with 8-point checklist.

backmark task ai-review-ready 42

Checks subtasks, dependencies, blockers, acceptance criteria, AI review, and more before allowing completion.

👀 Viewing AI Content

View All AI Sections at Once

backmark task view <task-id> --ai-all

This displays:

Task metadata (title, status, priority, etc.)
Task description
AI Plan section
AI Notes section
AI Documentation section
AI Review section
Acceptance criteria
Changelog

View Specific Sections

# Just the plan
backmark task view 42 --ai-plan

# Just the notes
backmark task view 42 --ai-notes

# Just the docs
backmark task view 42 --ai-doc

# Just the review
backmark task view 42 --ai-review

Edit Task Files Directly

Since tasks are Markdown files, you can edit them directly:

# Open in your editor
vim backlog/tasks/42.md
code backlog/tasks/42.md
nano backlog/tasks/42.md

Changes are reflected immediately!

🎯 Best Practices

For AI Planning:

✅ Be specific about implementation steps
✅ List all files that will be touched
✅ Identify dependencies early
✅ Consider edge cases and risks
✅ Update plan if approach changes

For AI Notes:

✅ Always include timestamps
✅ Document decisions with reasoning
✅ Log problems AND solutions
✅ Note deviations from plan
✅ Keep entries concise but complete

For AI Documentation:

✅ Write for future readers
✅ Include real code examples
✅ Document configuration options
✅ Add troubleshooting tips
✅ Keep it up-to-date

For AI Review:

✅ Be honest about limitations
✅ Report actual test results
✅ Ask questions when uncertain
✅ Suggest improvements
✅ Provide clear recommendation

The Four AI Spaces

1. ai_plan

2. ai_notes

3. ai_documentation

4. ai_review

📋 ai_plan - Implementation Planning

What Goes in ai_plan?

Command:

Example:

📝 ai_notes - Development Log

What Goes in ai_notes?

Command:

Example:

📚 ai_documentation - User Documentation

What Goes in ai_documentation?

Command:

Example:

✅ ai_review - Self-Review

What Goes in ai_review?

Command:

Example:

✅ Acceptance Criteria - Definition of Done

What Are Acceptance Criteria?

Why Use Acceptance Criteria?

Best Practices

Managing Acceptance Criteria

Add Criteria:

Check Off Completed Criteria:

Integration with AI Workflow

1. In AI Plan

2. In AI Review

3. Validation Before Closing:

🤖 AI Automation Features

ai-breakdown

ai-estimate

ai-review-ready

👀 Viewing AI Content

View All AI Sections at Once

View Specific Sections

Edit Task Files Directly

🎯 Best Practices

For AI Planning:

For AI Notes:

For AI Documentation:

For AI Review:

Start Using AI Workflow

1. `ai_plan`

2. `ai_notes`

3. `ai_documentation`

4. `ai_review`

`ai-breakdown`

`ai-estimate`

`ai-review-ready`