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`):

```bash
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:

```bash
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:

```markdown
# 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**: {YYYY-MM-DD}
```

Save to: `.agent/tasks/TASK-{XX}-{slug}.md`

### Step 3B: Archive Completed Task (If Feature Done)

Generate task document from conversation:

1. **Analyze conversation** (last 30-50 messages):
   - What was built?
   - How was it implemented?
   - What decisions were made?
   - What files were modified?

2. **Generate implementation plan**:

```markdown
# TASK-{XX}: {Feature Name}

**Status**: ✅ Completed
**Created**: {YYYY-MM-DD}
**Completed**: {YYYY-MM-DD}

---

## What Was Built

[1-2 paragraph summary of the feature]

---

## Implementation

### Phase 1: {Actual phase completed}
**Completed**: {Date}

**Changes**:
- Created `src/auth/oauth.ts` - OAuth provider integration
- Modified `src/routes/auth.ts` - Added login/logout endpoints
- Updated `src/config/passport.ts` - Passport configuration

**Key Code**:
```typescript
// Example of key implementation
export const oauthLogin = async (req, res) => {
  // Implementation details
};
```

### Phase 2: {Next phase}
...

---

## Technical Decisions

| Decision | Options | Chosen | Reasoning |
|----------|---------|--------|-----------|
| Auth library | next-auth, passport.js, auth0 | passport.js | Better control over OAuth flow, smaller bundle |
| Token storage | localStorage, cookies, sessionStorage | httpOnly cookies | XSS protection, automatic transmission |
| Session store | memory, Redis, PostgreSQL | Redis | Fast, scalable, separate from DB |

---

## Files Modified

- `src/auth/oauth.ts` (created) - OAuth integration
- `src/routes/auth.ts` (modified) - Added auth endpoints
- `src/config/passport.ts` (created) - Passport setup
- `tests/auth.test.ts` (created) - Auth tests
- `README.md` (updated) - OAuth setup instructions

---

## Challenges & Solutions

**Challenge**: OAuth callback URL mismatch
- **Problem**: Redirects failed in production
- **Solution**: Added environment-specific callback URLs
- **Commit**: abc1234

**Challenge**: Session persistence across restarts
- **Problem**: Users logged out on server restart
- **Solution**: Redis session store
- **Commit**: def5678

---

## Testing

- ✅ Unit tests: `src/auth/*.test.ts` (15 tests, 100% coverage)
- ✅ Integration tests: OAuth flow end-to-end
- ✅ Manual testing: Tested with Google, GitHub providers

---

## Documentation

- ✅ README updated with OAuth setup instructions
- ✅ Environment variables documented in `.env.example`
- ✅ API endpoints documented in `docs/api.md`

---

## Verify

Commands executed to validate:

```bash
# Actual commands run during verification
npm test src/auth
npm run type-check
npm run build
```

**Results**: All passed ✅

---

## Done

Outcomes confirmed:

- [x] `src/auth/oauth.ts` exports OAuth provider integration
- [x] All tests pass (15 tests, 100% coverage)
- [x] Build succeeds without errors
- [x] OAuth login/logout flows work correctly

---

## Related

**SOPs Created**:
- `.agent/sops/integrations/oauth-setup.md`

**System Docs Updated**:
- `.agent/system/project-architecture.md` (added auth section)

---

**Completed**: {YYYY-MM-DD}
**Implementation Time**: {X hours/days}
```

Save to: `.agent/tasks/TASK-{XX}-{slug}.md`

### Step 3.5: Verify Interpretation (ToM Checkpoint - Archive Mode Only) [EXECUTE]

**IMPORTANT**: This step MUST be executed when archiving tasks (not creating new ones).

**Before committing archive documentation, confirm interpretation with user**.

**Display verification** (only for ARCHIVE action):
```
I extracted this from our session:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What was built:
- {FEATURE_SUMMARY}

Key decisions captured:
- {DECISION_1}: {REASONING_1}
- {DECISION_2}: {REASONING_2}

Files changed: {COUNT} total
- {FILE_1} ({ACTION}: {PURPOSE})
- {FILE_2} ({ACTION}: {PURPOSE})

Challenges solved:
- {CHALLENGE_1}: {SOLUTION_1}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Corrections needed? [Enter to proceed / type corrections]
```

**Always verify for ARCHIVE** because:
- Extracting from conversation is inference-based
- User may have made decisions not explicitly stated
- Some files may have been modified outside conversation
- Ensures accurate historical record

**Skip verification for CREATE** because:
- Template is mostly empty
- User fills in details themselves
- No inference risk

### Step 4: Update Navigator Index

Edit `.agent/DEVELOPMENT-README.md` to add task to index:

```markdown
## Active Tasks

- **TASK-{XX}**: {Feature Name} (Status: In Progress/Completed)
  - File: `.agent/tasks/TASK-{XX}-{slug}.md`
  - Started: {Date}
  - [Completed: {Date}]
```

Keep index organized (active tasks first, completed below).

### Step 4.5: Sync to Knowledge Graph (v6.0.0+)

**If knowledge graph exists**, sync task to graph:

```bash
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/task_to_graph.py" \
    --action add \
    --task-path ".agent/tasks/TASK-{XX}-{slug}.md" \
    --graph-path .agent/knowledge/graph.json
fi
```

**What this does**:
- Extracts concepts from task content (auth, api, testing, etc.)
- Adds task node to graph with status and concepts
- Creates `implements` edges from task to concepts
- For **completed tasks**: Extracts Technical Decisions as `decision` memories

**Output**:
```
Added task: TASK-XX
Title: {Feature Name}
Status: completed
Concepts: auth, api, testing
Decisions extracted: 2
```

This makes the task queryable via "What do we know about auth?" and preserves architectural decisions as persistent memories.

### Step 5: Update PM Tool (If Configured)

**If PM tool is Linear**:
```typescript
create_comment({
  issueId: "TASK-XX",
  body: "📚 Implementation plan documented: .agent/tasks/TASK-XX-feature.md"
})
```

**If PM tool is GitHub**:
```bash
gh issue comment {ISSUE-NUMBER} -b "📚 Implementation plan: .agent/tasks/TASK-XX-feature.md"
```

**If PM tool is none**:
Skip PM update.

### Step 6: Confirm Success

Show completion message:

```
✅ Task documentation created!

Task: TASK-{XX} - {Feature Name}
File: .agent/tasks/TASK-{XX}-{slug}.md
Size: {X} KB (~{Y} tokens)

📋 Contains:
- Implementation phases
- Technical decisions
- Files modified
- [If archived: Challenges & solutions]
- [If archived: Testing & documentation]

🔗 Navigator index updated
[If PM tool: PM tool comment added]

To reference later:
Read .agent/tasks/TASK-{XX}-{slug}.md
```

## Task Document Template Structure

### For New Tasks (Planning)
1. Context (problem/goal)
2. Acceptance criteria (`- [ ]` checkable outcomes)
3. Implementation (phases)
4. Out of scope (explicit non-goals)
5. Technical decisions (to be made)
6. Verify + Done (validation + completion)
7. Refs (sources/related)

### For Completed Tasks (Archive)
1. What was built (summary)
2. Implementation (actual phases)
3. Technical decisions (what was chosen)
4. Files modified
5. Challenges & solutions
6. Testing & documentation

## Common Use Cases

### Starting New Feature
```
User: "Create task doc for payments integration"
→ Generates TASK-07-payments.md
→ Empty template for planning
→ User fills in as they work
```

### Completing Feature
```
User: "Document the auth feature I just finished"
→ Analyzes conversation
→ Generates TASK-06-auth.md
→ Complete implementation record
→ Archives for future reference
```

### Mid-Feature Update
```
User: "Update TASK-05 with OAuth decision"
→ Reads existing TASK-05-auth.md
→ Adds to Technical Decisions section
→ Preserves rest of document
```

## Error Handling

**Navigator not initialized**:
```
❌ .agent/tasks/ directory not found

Run /nav:init to set up Navigator structure first.
```

**Task ID already exists (for creation)**:
```
⚠️  TASK-{XX} already exists

Options:
1. Read existing task
2. Use different ID
3. Archive/overwrite existing

Your choice [1-3]:
```

**Insufficient context to archive**:
```
⚠️  Not enough conversation context to generate implementation plan

Consider:
- Provide more details about what was built
- Manually create task doc
- Skip archiving

Continue with template? [y/N]:
```

## Success Criteria

Task documentation is successful when:
- [ ] Task file created in `.agent/tasks/`
- [ ] Filename follows convention: `TASK-{XX}-{slug}.md`
- [ ] Contains all required sections
- [ ] Navigator index updated
- [ ] PM tool updated (if configured)
- [ ] User can reference task later

## Scripts

**generate_task.py**: Create task documentation from conversation
- Input: Conversation history, task ID
- Output: Formatted task markdown

**update_index.py**: Update DEVELOPMENT-README.md task index
- Input: New task info
- Output: Updated index

## Best Practices

**Good task slugs**:
- `oauth-implementation` (descriptive)
- `stripe-payment-flow` (clear purpose)
- `user-profile-page` (specific feature)

**Bad task slugs**:
- `feature` (too vague)
- `fix` (not descriptive)
- `task1` (meaningless)

**When to create task docs**:
- ✅ Starting major feature (> 1 day work)
- ✅ Completing any feature (archive)
- ✅ Complex implementation (capture decisions)
- ❌ Tiny bug fixes (use SOPs instead)
- ❌ Exploratory work (wait until direction clear)

## Notes

Task docs are **living documents**:
- Created when starting feature (template)
- Updated during implementation (decisions)
- Finalized when complete (archive)

They serve as:
- Planning tool (before implementation)
- Progress tracker (during implementation)
- Historical record (after completion)
- Knowledge base (for team/future)

This skill provides same functionality as `/nav:doc feature` command but with natural language invocation.