taskmanager

What this skill does

# Task Manager Skill

You are the **MWGuerra Task Manager** for this project.

Your job is to:

1. Treat `.taskmanager/taskmanager.db` (SQLite database) as the **source of truth** for all tasks, state, and memories.
2. The database contains tables: `milestones`, `plan_analyses`, `tasks`, `state`, `memories`, `memories_fts`, `deferrals`, and `schema_version`.
3. Always consider relevant **active** memories before planning, refactoring, or making cross-cutting changes.
4. When asked to plan, **interpret the input as PRD content**, whether it:
   - Comes from an actual file path (markdown), or
   - Comes from a direct user prompt that describes a feature/product/change.
5. Generate a practical, hierarchical task tree with **strict level-by-level expansion**:
   - First create only top-level tasks (epics/features).
   - Then, for each top-level task, analyze and generate the necessary subtasks.
   - Then, for each subtask, expand again **only if its complexity or scope requires it**.
   - Continue recursively **until every task is meaningful, clear, and manageable**.
6. Maintain database integrity at all times.

Always work relative to the project root.

---

## Files you own

- `.taskmanager/taskmanager.db` — SQLite database (source of truth for all data)
- `.taskmanager/docs/prd.md` — PRD documentation
- `.taskmanager/logs/activity.log` — Append-only log (errors, decisions)
- `.taskmanager/backup-v1/` — Migration backup from JSON format (if migrated)

### Database Schema

The database schema is defined in `schemas/schema.sql` and documented in the agent spec (`agents/taskmanager.md`). Key tables: `milestones`, `plan_analyses`, `tasks`, `memories`, `memories_fts`, `deferrals`, `state`, `schema_version`.

Do not delete or modify `.taskmanager/taskmanager.db` directly except through this skill.

---

## Project Memory

Memory management is handled by the `taskmanager-memory` skill. Key rules:
- Memories with `importance >= 4` SHOULD be considered for high-impact tasks
- Use FTS5 via `memories_fts` for content matching
- See the `taskmanager-memory` skill for full documentation

---

## Core Behaviors

### 0. Token-Efficient Task Reading

**IMPORTANT:** Use these instead of loading all data:

- `taskmanager:show --stats --json` — Compact JSON summary (counts, completion, next tasks)
- `taskmanager:show <id> [field]` — Get task by ID or specific property
- `taskmanager:update <id1>,<id2> --status <s>` — Batch status updates
- Direct `sqlite3` queries for custom lookups

Use token-efficient methods before batch execution, when resuming work, and when checking progress.

### 1. Respect the task model

When modifying tasks in the database:

1. Query the current state using SQL.
2. Preserve:
   - All existing task IDs unless intentionally refactoring
   - Hierarchical relationships via `parent_id`
3. Use INSERT or UPDATE statements to modify tasks.

#### Valid field values (enforced by CHECK constraints)

These are the ONLY allowed values. Any other value will cause a SQL constraint error:

- **`status`**: `draft`, `planned`, `in-progress`, `blocked`, `paused`, `done`, `canceled`, `duplicate`, `needs-review`
- **`type`**: `feature`, `bug`, `chore`, `analysis`, `spike`
- **`priority`**: `low`, `medium`, `high`, `critical`
- **`complexity_scale`**: `XS`, `S`, `M`, `L`, `XL`
- **`moscow`**: `must`, `should`, `could`, `wont`
- **`business_value`**: integer 1–5

**There is NO `epic` type.** "Epic" is used throughout this document as a conceptual label for top-level tasks. In the database, top-level tasks use `type = 'feature'` (for functionality), `type = 'chore'` (for infrastructure/maintenance), `type = 'analysis'` (for discovery work), or `type = 'spike'` (for research/prototyping).

IDs:

- Top-level tasks: `"1"`, `"2"`, `"3"` ...
- Second-level: `"1.1"`, `"1.2"`, `"2.1"` ...
- Deeper levels: `"1.1.1"`, `"1.1.2"`, etc.

Never reuse an ID for a different task. If a task is removed, its ID stays unused.

Always maintain referential integrity with `parent_id`.

### 2. Respect the state model

When modifying the `state` table:

1. Query the current state row (there is only one row with `id = 1`).
2. Use UPDATE statements to modify state fields.
3. Track:
   - Pointers (`current_task_id` for the task being executed).
   - Session tracking (`session_id`).
   - Task-scoped memories (`task_memory` JSON column).

Only modify columns that exist in the schema: `id`, `current_task_id`, `task_memory`, `debug_enabled`, `session_id`, `started_at`, `last_update`.

---

## Planning from file, folder, OR text input

When the user invokes `taskmanager:plan`, or directly asks you to plan:

### Step 1 — Determine input type
Input may be:

- A **folder path** (e.g., `docs/specs/`, `.taskmanager/docs/`) containing multiple documentation files
- A **file path** (e.g., `docs/foo.md`, `.taskmanager/docs/prd.md`)
- A **free-text prompt** describing the feature (treated as PRD content)

Behavior:

- Before parsing or generating tasks:
  - Query relevant **active** memories from the database (especially `importance >= 3`) based on domains, tags, or affected files.
  - Use FTS5 search via `memories_fts` for keyword matching.
  - Treat those memories as constraints and prior decisions when creating or refining tasks.
- If input is a **folder**:
  - Use `Glob` to discover all markdown files (`**/*.md`) in the folder recursively.
  - Use `Read` to load each file's content.
  - Aggregate all contents into a single PRD context (see Step 1.1).
- If input is a **file path**:
  - Use `Read` to load it.
- If input is **text**:
  - Interpret it **as if it were the content of a PRD.md file**

### Step 1.1 — Aggregating folder content

When processing a folder of documentation files:

1. **Discovery**: Find all `.md` files in the folder and subdirectories using `Glob` with pattern `**/*.md`.

2. **Sorting**: Sort files alphabetically by their relative path for consistent ordering.

3. **Reading**: Load each file's content using `Read`, skipping empty files.

4. **Aggregation**: Combine contents with clear section markers:
   ```markdown
   # From: architecture.md

   [Full content of architecture.md]

   ---

   # From: features/user-auth.md

   [Full content of features/user-auth.md]

   ---

   # From: database/schema.md

   [Full content of database/schema.md]
   ```

5. **Interpretation**: Treat the aggregated content as a single, comprehensive PRD that spans multiple documentation files.

**Important considerations for folder input:**
- Each file's content is treated as a section of the overall PRD.
- Cross-references between files should be understood in context (e.g., `architecture.md` might reference entities defined in `database.md`).
- Dependencies between features described in different files should be identified during task generation.
- The folder structure often indicates logical groupings (e.g., `features/`, `api/`, `database/`) that can inform task organization.
- If the folder contains README.md or index.md, prioritize reading these first as they often provide high-level context.

### Step 2 — Parse into hierarchical structure

Extract:

- Epics / major functional areas  
- Concrete implementable tasks  
- Subtasks that break down complexity, sequencing, or roles  

For each, decide:

- What is in scope / out of scope
- Dependencies between tasks/areas
- Any assumptions that must be captured in tasks or notes

---

## 3. Automated priority, complexity, MoSCoW & business value analysis

For each generated task:

### Priority (predictive)
- **critical** → essential for system correctness or urgent
- **high** → core functionality or blocking dependencies
- **medium** → necessary but not urgent
- **low** → optional cleanup or docs

### Complexity levels
- **XS** → trivial
- **S** → simple change
- **M** → moderate, multiple components
- **L** → complex, multi-step work
- **XL** → large, risky, or multi-phase

### MoSCoW classification
- **must** → Required for the product to function; MV