---
inclusion: always
---

# Factbase MCP Bug Reporting and Feature Requests

## When to File a Bug

Whenever you use any `mcp_factbase_*` tool and encounter ANY of the following, you MUST submit a task to the Vikunja board:

- **Errors**: MCP errors, panics, internal errors, timeouts, or unexpected exceptions
- **Unexpected results**: Tool returns success but the output is wrong, incomplete, or nonsensical
- **Data corruption**: Documents modified incorrectly, content lost, formatting broken after an operation
- **Silent failures**: Tool claims success but nothing actually changed (e.g. apply_review_answers says it applied N answers but files are unchanged)
- **Missing functionality**: A tool doesn't behave as its description says it should
- **Performance issues**: Operations that take unreasonably long or hang

Do NOT wait for the user to ask you to file a bug. File it proactively as soon as you notice the issue, then continue with your work.

## How to File

```
curl -X PUT https://vikunja.home.everyonce.com/api/v1/projects/2/tasks \
  -H "Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "[factbase] <short bug summary>",
    "description": "<detailed description including:\n- Which MCP tool was called\n- What parameters were passed\n- What the expected behavior was\n- What actually happened (include error message if any)\n- Any workaround used>",
    "priority": 3
  }'
```

### Priority Guide
- **1-2**: Minor cosmetic issues, suggestions for improvement
- **3**: Normal bugs — tool errors, unexpected behavior
- **4**: Significant bugs — data loss, corruption, tools that are completely broken
- **5**: Urgent — blocking all factbase operations

### API Details
- Base URL: `https://vikunja.home.everyonce.com/api/v1`
- Auth: `Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8`
- Project ID: 2 (OpenClaw Tasks)
- Tasks land in the To-Do bucket (id: 4) by default

### Check Task Status

```
# Get a specific task
curl https://vikunja.home.everyonce.com/api/v1/tasks/<task_id> \
  -H "Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8"

# List all tasks in the project
curl "https://vikunja.home.everyonce.com/api/v1/projects/2/tasks" \
  -H "Authorization: Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8"
```

A task is complete when `"done": true`.

### Kanban Buckets
- Backlog (7) — queued, not yet started
- To-Do (4) — ready for work ← tasks land here by default
- Doing (5) — in progress
- Done (6) — completed

### Rules
- Always prefix task titles with `[factbase]`
- Include enough detail in the description to reproduce the bug
- Don't assign — the local dev agent picks up and runs tasks automatically
- Mention the agent session context briefly (e.g. "while running LinkedIn discovery workflow" or "during factbase review answer application")
- If you worked around the issue, describe the workaround in the description

## When to File a Feature Request

Beyond bugs, you should ALSO proactively file feature requests when you notice friction, gaps, or missed opportunities while using factbase. Specifically:

- **Missing MCP tools**: CLI commands that exist but aren't exposed via MCP (e.g. `organize`, `merge`, `split`, `move`)
- **Workflow friction**: Multi-step operations that should be a single tool call, or common patterns that require awkward workarounds
- **Data quality gaps**: The review queue or check system misses something it should catch, or flags things it shouldn't (e.g. recursive questions about its own review queue)
- **Search/retrieval limitations**: Queries that should work but don't, or results that are missing obvious matches
- **Disambiguation improvements**: Acronyms and terms that keep getting flagged as ambiguous when they're standard industry/AWS terminology — suggest the system learn them
- **Enrichment automation**: Patterns you repeat manually that factbase could automate (e.g. auto-expanding known acronyms, auto-linking entity mentions, bulk temporal tag updates)
- **Organization improvements**: Better type detection, folder structure suggestions, duplicate detection improvements, or smarter merge/split recommendations
- **Agent ergonomics**: Anything that would make the agent's use of factbase smoother — better error messages, more useful return values, pagination improvements, etc.

File these the same way as bugs, but use priority 1-2 and prefix with `[factbase][feature]`:

```
$headers = @{ "Authorization" = "Bearer tk_ff251f3d3512775c71913bc2f8ec0dabbf5016a8"; "Content-Type" = "application/json" }
$body = '{"title":"[factbase][feature] <short feature summary>","description":"<what the feature would do, why it matters, example use case>","priority": 2}'
Invoke-RestMethod -Method Put -Uri "https://vikunja.home.everyonce.com/api/v1/projects/2/tasks" -Headers $headers -Body $body
```

### Feature Request Priority
- **1**: Nice-to-have, low impact — cosmetic or minor convenience
- **2**: Meaningful improvement — reduces friction, saves time, improves data quality
- **3**: Important gap — blocking a common workflow or causing repeated manual workarounds