/nav-task

name: nav-task
description: Manage Navigator task documentation - create implementation plans, archive completed tasks, update task index. Use when user starts new feature, completes work, or says "document this feature".
allowed-tools: Read, Write, Edit, Bash
version: 1.0.0

Navigator Task Manager Skill

Create and manage task documentation - implementation plans that capture what was built, how, and why.

When to Invoke

Invoke this skill when the user:

• Says "document this feature", "archive this task"
• Says "create task doc for...", "document what I built"
• Completes a feature and mentions "done", "finished", "complete"
• Starts new feature and says "create implementation plan"

**DO NOT invoke** if:

• User is asking about existing tasks (use Read, not creation)
• Creating SOPs (that's nav-sop skill)
• Updating system docs (different skill)

Execution Steps

Step 1: Determine Task ID

**If user provided task ID** (e.g., "TASK-01", "GH-123"):

• Use their ID directly

**If no ID provided**, run the generator — it reads `task_id_source` from `.agent/.nav-config.json` (default `local`):

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-task/functions/task_id_generator.py" \
  --title "{feature name}" --body "{one-line summary}" --json

• `task_id_source: local` (solo repos) — next sequential `{task_prefix}-NN` from

`.agent/tasks/` (last is TASK-05 → TASK-06). `--title` is ignored.

• `task_id_source: github` (team repos, GH-32) — creates the GitHub issue first via

`gh issue create` and returns `GH-<n>`; the doc is `.agent/tasks/GH-<n>-{slug}.md`. Issue numbers are allocated by GitHub, so two contributors branching at once can never mint the same ID, and Pilot already addresses tasks as `GH-<n>`. Add `--label pilot` (or any label) when the issue should be picked up. A failing `gh` (no auth, no network) is an error — do **not** fall back to a local number; tell the user and stop.

• Existing `TASK-NN` docs keep working either way; the index, graph sync and

session-start listing accept any `PREFIX-<n>` filename.

• In the doc template below, `TASK-{XX}` stands for whichever ID came back.

Step 2: Determine Action (Create vs Archive)

**Creating new task** (starting feature):

User: "Create task doc for OAuth implementation"
→ Action: CREATE
→ Generate empty implementation plan template

**Archiving completed task** (feature done):

User: "Document this OAuth feature I just built"
→ Action: ARCHIVE
→ Generate implementation plan from conversation

Step 2.5: Recall Prior Knowledge (CREATE flow only, v6.17.0+)

Before writing the plan, query the knowledge graph for memories relevant to this feature — pitfalls and patterns the project has already paid for:

PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"

if [ -f ".agent/knowledge/graph.json" ]; then
  python3 "$PLUGIN_DIR/skills/nav-graph/functions/memory_recall.py" \
    --concepts "{comma-separated concepts inferred from the feature description}" \
    --format markdown --limit 5
fi

• Infer concepts from the feature description using the same keyword

families as `task_to_graph.extract_concepts_from_task` (auth, database, api, frontend, testing, …) — alias resolution absorbs abbreviations.

• **Empty output → skip silently.** Do not add the section; do not mention

the absence.

• Non-empty output → include it as the `## Known Pitfalls & Patterns`

section in the template below, and **reflect each recalled pitfall in the Implementation phases** (a recalled pitfall that doesn't change the plan wasn't really factored in).

Step 3A: Create New Task (If Starting Feature)

Generate task document from template:

# TASK-{XX}: {Feature Name}

**Status**: 🚧 In Progress
**Created**: {YYYY-MM-DD}
**Assignee**: {from PM tool or "Manual"}

---

## Context

**Problem**:
[What problem does this solve?]

**Goal**:
[What are we building?]

---

## Known Pitfalls & Patterns

<!-- From knowledge graph (Step 2.5). OMIT this section entirely if recall
     returned nothing. Each recalled pitfall must be reflected in the
     Implementation phases below. -->

- **PITFALL** (90%, mem-XXX): [recalled summary]

---

## Acceptance Criteria

Concrete, checkable outcomes — written so anyone (human or AI) can verify them.

- [ ] [Specific, observable outcome]
- [ ] [Another outcome]
- [ ] [Edge case handled]

---

## Implementation

### Phase 1: {Name}
**Goal**: [What this phase accomplishes]

**Tasks**:
- [ ] [Specific task]
- [ ] [Another task]

**Files**:
- `path/to/file.ts` - [Purpose]

### Phase 2: {Name}
...

---

## Out of Scope

Explicit non-goals — what this task deliberately does not address.

- [What's deferred to a future task]
- [Adjacent change being avoided]

---

## Technical Decisions

| Decision | Options Considered | Chosen | Reasoning |
|----------|-------------------|--------|-----------|
| [What] | [Option A, B, C] | [Chosen] | [Why] |

---

## Verify

Run these commands to validate the implementation:

```bash
# Run tests
[test command for this feature]

# Type check
[type check command]

# Build
[build command]

---

Done

Observable outcomes that prove completion:

• [ ] [Specific file/API exists and exports expected interface]
• [ ] [Tests pass - specify count or coverage target]
• [ ] [Build succeeds without errors]
• [ ] [User-observable behavior works as specified]

---

Refs

• [Source plan / design doc / parent issue]
• [Related ticket]

---

Notes

[Any additional context, links, references]

---

**Last Updated**