workflow

What this skill does

# contextd Workflow

## Session Start Protocol

**Step 1: Search for relevant memories**
```json
{
  "project_id": "contextd",
  "query": "current task context",
  "limit": 5
}
```

**Step 2: Check for checkpoints**
```json
{
  "tenant_id": "fyrsmithlabs",
  "project_path": "/path/to/project",
  "limit": 5
}
```

**Step 3: If checkpoint found**
- Ask user: "Found previous work: '[summary]'. Resume?"
- If yes: `checkpoint_resume(checkpoint_id, tenant_id, level)`
- Levels: `summary` (minimal), `context` (balanced), `full` (complete)

## Checkpoint Workflow

**When to checkpoint:**
- Context >= 70% capacity
- End of work session
- Before risky operations
- Switching tasks

### checkpoint_save

```json
{
  "session_id": "session_abc123",
  "tenant_id": "fyrsmithlabs",
  "project_path": "/path/to/project",
  "name": "Feature implementation checkpoint",
  "summary": "Completed: spec, 2 of 4 skills. Next: remaining skills.",
  "context": "Working on plugin consolidation...",
  "full_state": "Complete conversation state...",
  "token_count": 45000,
  "threshold": 0.7,
  "auto_created": false
}
```

**Summary must include:**
- What was accomplished
- What's in progress
- What's next
- Key decisions made

### Resume Levels

| Level | Tokens | Content |
|-------|--------|---------|
| `summary` | ~100-200 | Name + summary only |
| `context` | ~500-1000 | Summary + context + decisions |
| `full` | Complete | Entire conversation history |

## Error Remediation Flow

**When encountering ANY error:**

```
1. DIAGNOSE the error
   troubleshoot_diagnose(error_message, error_context)

2. SEARCH for past fixes
   remediation_search(query, tenant_id)

3. APPLY fix (use diagnosis + history)

4. RECORD the solution
   remediation_record(title, problem, root_cause, solution, category)
```

### troubleshoot_diagnose

```json
{
  "error_message": "cannot use vectorStore as vectorstore.Store value",
  "error_context": "Running go test after adding new interface method"
}
```

Returns: `root_cause`, `hypotheses`, `recommendations`, `confidence`

### remediation_record

```json
{
  "title": "Mock missing interface method after interface change",
  "problem": "Test fails with 'missing method X'",
  "symptoms": ["go test fails", "cannot use X as Y value"],
  "root_cause": "Mock implementations don't get new interface methods",
  "solution": "Add new method to all mock implementations",
  "category": "syntax",
  "tenant_id": "fyrsmithlabs",
  "scope": "org"
}
```

**Categories:** `syntax`, `runtime`, `logic`, `config`, `dependency`, `network`, `auth`, `data`, `performance`

**Scopes:** `project` (this project), `team` (team members), `org` (entire organization)

## Session End Protocol

**Before `/clear` or ending work:**

1. **Re-index repository**
   ```json
   { "path": "." }
   ```
   Captures code changes and updates branch metadata.

2. **Record learnings**
   ```json
   {
     "project_id": "contextd",
     "title": "Implemented session lifecycle hooks",
     "content": "Used TDD with Registry pattern...",
     "outcome": "success",
     "tags": ["hooks", "lifecycle", "tdd"]
   }
   ```

3. **Checkpoint if resuming later**
   ```json
   { "auto_created": true, "threshold": 0.7, ... }
   ```

## Git Commit Re-index

**After every `git commit`:**
```json
{ "path": "." }
```

Why: Captures changes for semantic search, updates branch metadata.

## Quick Reference

| When | Action |
|------|--------|
| Session start | `memory_search` + `checkpoint_list` |
| After git commit | `repository_index` |
| Context >= 70% | `checkpoint_save` then `/clear` |
| Error encountered | `troubleshoot_diagnose` -> `remediation_search` -> fix -> `remediation_record` |
| Before `/clear` | `memory_record` + `checkpoint_save` |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Skipping memory search at start | Always search first |
| Vague checkpoint summaries | Include completed/in-progress/next |
| Waiting until context overflow | Save at 70%, not 95% |
| Not recording before `/clear` | Call `memory_record` first |
| Skipping error diagnosis | `troubleshoot_diagnose` first, always |

## Input Validation (contextd v1.5+)

### ID Format Requirements

`tenant_id` and `project_id` must be lowercase alphanumeric with underscores:
- **Valid**: `my_project`, `contextd`, `org123`
- **Invalid**: `My-Project`, `org/repo`, `project..name`
- **Length**: 1-64 characters

### Path Validation

All `project_path` parameters are validated:
- No directory traversal (`../` is rejected)
- Use absolute paths or paths within the current project

### Validation Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `invalid tenant_id` | Invalid characters | Use lowercase, underscores only |
| `invalid project_path` | Directory traversal | Use absolute or relative-to-project paths |
| `invalid patterns` | Shell injection chars | Remove `;`, `\|`, `` ` ``, `$` |

---

## Checkpoint Compression (Deltas)

### Delta-Based Storage

Instead of storing full state each time, checkpoints can store deltas:

```json
{
  "checkpoint_id": "cp_002",
  "parent_id": "cp_001",
  "storage_mode": "delta",
  "delta": {
    "added_memories": ["mem_123", "mem_124"],
    "completed_tasks": ["#42", "#43"],
    "new_decisions": ["Use Registry pattern for DI"],
    "files_changed": ["api/handler.go", "internal/store.go"]
  },
  "delta_size_tokens": 150,
  "full_size_tokens": 2500
}
```

### Compression Modes

| Mode | Storage | Restore Speed | Use Case |
|------|---------|---------------|----------|
| `full` | Complete state | Instant | Short sessions, critical points |
| `delta` | Changes only | Requires chain | Long sessions, frequent saves |
| `hybrid` | Full every 5th | Balanced | Default recommendation |

### Checkpoint Chain

```
cp_001 (full) -> cp_002 (delta) -> cp_003 (delta) -> cp_004 (delta) -> cp_005 (full)
                                                                        ^
                                                              Auto-consolidate at 5
```

Resume from delta:
```
checkpoint_resume(checkpoint_id: "cp_003")
  -> Loads cp_001 (full base)
  -> Applies cp_002 delta
  -> Applies cp_003 delta
  -> Returns reconstructed state
```

---

## Checkpoint Branching

### Parallel Work Streams

Create checkpoint branches for exploration:

```json
{
  "checkpoint_id": "cp_main_005",
  "branch": "experiment/new-arch",
  "parent_checkpoint": "cp_main_003",
  "description": "Exploring event-sourcing architecture"
}
```

### Branch Operations

| Operation | Purpose |
|-----------|---------|
| `checkpoint_branch(parent_id, branch_name)` | Create exploration branch |
| `checkpoint_merge(branch_id, target_id)` | Merge learnings back |
| `checkpoint_abandon(branch_id)` | Discard failed experiment |

### Visualizing Branches

```
cp_main_001 -> cp_main_002 -> cp_main_003 -> cp_main_004 -> cp_main_005
                                    \
                                     -> cp_exp_001 -> cp_exp_002 (merged at cp_main_005)
```

---

## Auto-Error Capture via Hooks

### PostToolUse Hook for Error Detection

Automatically capture errors when tools fail:

```json
{
  "hook_type": "PostToolUse",
  "matcher": "Bash|Task",
  "condition": "tool_output.exit_code != 0 OR tool_output.contains('error')",
  "prompt": "An error occurred. Automatically:\n1. Call troubleshoot_diagnose with the error\n2. Search remediation_search for past fixes\n3. If novel error, prepare remediation_record after fix"
}
```

### PreToolUse Hook for Dangerous Operations

Checkpoint before risky operations:

```json
{
  "hook_type": "PreToolUse",
  "matcher": "Bash",
  "condition": "command.matches('rm|drop|delete|truncate|reset --hard')",
  "prompt": "Risky operation detected. Auto-checkpoint before proceeding:\ncheckpoint_save(name: 'pre-risky-op', auto_created: true)"
}
```

### Stop Hook for Session End

Auto-capture learnings when session ends:

```json
{
  "hook_type": "Stop",
  "prompt": "Session ending. Before final response:\n1. Record any unre