---
phase: 14-documentation-content-refinement-and-quality-pass
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - docs/best-practices.md
  - docs/agents.md
autonomous: true
requirements: []

must_haves:
  truths:
    - "best-practices.md exists with opinionated anti-pattern/correct-pattern entries for vault, notes, tags, links, sessions, plugins, and agent workflows"
    - "agents.md exists with machine-readable entity schemas, lifecycle state machines, constraint rules, and deterministic interaction flows"
    - "best-practices.md is 200-350 lines — aggregation, not tutorial"
    - "agents.md is 300-500 lines — structured data over prose"
    - "best-practices.md uses mentor tone (User Guide audience)"
    - "agents.md uses structured/deterministic format (Agent audience)"
  artifacts:
    - path: "docs/best-practices.md"
      provides: "Opinionated best practices and anti-patterns reference"
      min_lines: 200
    - path: "docs/agents.md"
      provides: "Machine-readable agent system manual"
      min_lines: 300
  key_links:
    - from: "docs/best-practices.md"
      to: "docs/tutorial.md"
      via: "cross-link in Next Steps"
      pattern: "tutorial"
    - from: "docs/agents.md"
      to: "docs/mcp.md"
      via: "cross-link to MCP tool catalog"
      pattern: "mcp"
---

<objective>
Create the two new documentation pages: best-practices.md (human-focused anti-pattern reference for User Guide) and agents.md (machine-readable system manual for Developer Guide). These serve fundamentally different audiences and reading patterns.

Purpose: Fill the two content gaps identified during phase discussion — an opinionated reference for common mistakes, and a structured system manual for LLM consumers.
Output: Two new documentation files ready for mkdocs.yml nav integration in Plan 05.
</objective>

<execution_context>
@/Users/shparki/.claude/get-shit-done/workflows/execute-plan.md
@/Users/shparki/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/14-documentation-content-refinement-and-quality-pass/14-CONTEXT.md
@.planning/phases/14-documentation-content-refinement-and-quality-pass/14-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create best-practices.md — opinionated anti-pattern reference</name>
  <files>docs/best-practices.md</files>
  <read_first>
    - docs/tutorial.md (mine workflow patterns and common pitfalls)
    - docs/plugins.md (mine batch vs immediate mode pitfall, config patterns)
    - docs/concepts.md (mine tag format domain/scope pattern)
    - docs/agentic-workflows.md (mine session discipline patterns)
    - docs/configuration.md (mine threshold tuning patterns — read AFTER Plan 01 applies fixes, or read models.py directly)
    - src/ztlctl/config/models.py (verify config defaults for threshold recommendations)
    - src/ztlctl/domain/types.py (verify content types, lifecycle states for accurate references)
  </read_first>
  <action>
Create docs/best-practices.md as an opinionated best-practices and anti-patterns reference page. Target 200-350 lines. Mentor/teacher tone (User Guide audience).

**Structure:**
```
# Best Practices

[1-2 sentences: "Opinionated guidance from building and maintaining ztlctl vaults. Each entry: what goes wrong, why it happens, and the correct pattern."]

## Vault Initialization
- Anti-pattern: Skipping `ztlctl init` and creating the DB manually
- Best practice: Always use `ztlctl init` with a profile (--profile obsidian for Obsidian users)
- Anti-pattern: Initializing in a deeply nested subdirectory

## Note Creation
- Anti-pattern: Creating notes without links (orphan accumulation)
- Best practice: Always include at least one --links reference or let reweave suggest connections
- Anti-pattern: Using the wrong content type (note vs reference vs task)
- Include guidance on when to use each type

## Tagging
- Anti-pattern: Bare tags like "python" without domain/scope
- Best practice: Use domain/scope format: "lang/python", "framework/fastapi"
- Explain: unscoped tags work but cannot be filtered with --tag "domain/..."

## Linking and Reweave
- Anti-pattern: Manually maintaining all links without reweave
- Best practice: Let reweave suggest connections, review in sessions
- Anti-pattern: Setting reweave threshold too low (noise) or too high (missing connections)
- Best practice: Start with defaults (min_score: 0.3, max_suggestions: 5), tune after 50+ notes

## Session Management
- Anti-pattern: Never closing sessions (state accumulates)
- Best practice: Close sessions after completing a work unit, review the enrichment report
- Anti-pattern: Running multiple concurrent sessions

## Plugin Configuration
- Anti-pattern: Enabling git plugin without understanding commit triggers
- Best practice: Start with batch_commits=true, auto_push=false
- Anti-pattern: Disabling reweave globally when you only want to skip it for specific operations

## Agent Workflows
- Anti-pattern: Agents creating notes without sessions (no context boundary)
- Best practice: Always wrap agent work in session start/close
- Anti-pattern: Agents ignoring ServiceResult error fields
- Best practice: Check .success before proceeding, use .recovery hint on failure

## What Not to Do (Summary Table)

| Anti-Pattern | Impact | Fix |
|-------------|--------|-----|
| Bare tags | Can't filter by domain | Use domain/scope |
| Orphan notes | Graph gaps, missed connections | Always link or let reweave |
| Manual DB edits | Corrupt indexes, broken FTS | Use CLI/MCP only |
| ... | ... | ... |

## Next Steps
- [Tutorial](tutorial.md) — hands-on walkthrough
- [Configuration](configuration.md) — tune thresholds
- [Agentic Workflows](agentic-workflows.md) — session discipline for agents
```

Use `!!! warning "Anti-Pattern: ..."` admonitions for the most critical anti-patterns (3-4 max, not every entry). Keep entries concise — 3-5 lines each. Cross-link to authoritative pages for full context.
  </action>
  <verify>
    <automated>test -f docs/best-practices.md && wc -l docs/best-practices.md | awk '{print ($1 >= 200) ? "OK: "$1" lines" : "TOO SHORT: "$1" lines"}'</automated>
  </verify>
  <acceptance_criteria>
    - docs/best-practices.md exists
    - File is 200-350 lines
    - Contains H2 sections: "Vault Initialization", "Note Creation", "Tagging", "Linking and Reweave", "Session Management", "Plugin Configuration", "Agent Workflows"
    - Contains "What Not to Do" summary table
    - Contains "Next Steps" section with cross-links
    - Contains at least 2 `!!! warning` admonitions
    - Contains "domain/scope" tag format guidance
    - Contains link to tutorial.md
    - Contains link to configuration.md
  </acceptance_criteria>
  <done>best-practices.md is a 200-350 line opinionated reference with anti-pattern/correct-pattern entries for all major ztlctl workflows, admonition callouts, summary table, and cross-links</done>
</task>

<task type="auto">
  <name>Task 2: Create agents.md — machine-readable system manual</name>
  <files>docs/agents.md</files>
  <read_first>
    - src/ztlctl/domain/types.py (content types, lifecycle states, enums)
    - src/ztlctl/domain/lifecycle.py (state machine transitions if exists)
    - src/ztlctl/actions/definitions.py (ActionDefinition, ActionParam — system capabilities)
    - src/ztlctl/actions/registry.py (ActionRegistry — capability enumeration)
    - src/ztlctl/mcp/tools.py (MCP tool definitions for interaction patterns)
    - src/ztlctl/mcp/resources.py (MCP resource definitions)
    - src/ztlctl/services/create.py (create pipeline stages for deterministic flow docs)
    - src/ztlctl/services/session.py (session lifecycle for agent session flow)
    - docs/mcp.md (existing MCP docs — avoid duplication, cross-link instead)
    - docs/agentic-workflows.md (human-focused counterpart — ensure no tone duplication)
  </read_first>
  <action>
Create docs/agents.md as a machine-readable system manual for LLM consumers. Target 300-500 lines. Structured/deterministic format — tables, schemas, code blocks over prose. This page is for agents, not humans.

**Structure:**
```
# Agent System Manual

> This page is for LLM systems consuming ztlctl via MCP or CLI. For human-readable workflow guides, see [Agentic Workflows](agentic-workflows.md).

## System Capabilities

Table with columns: Capability, Access Method (CLI/MCP), Category, Description
List all major operations grouped by category (content, query, graph, session, check, export, docs).

## Entity Schemas

### Note
Table: field name, type, constraints, description
Required fields: title (str, 3-200 chars), content_type (note|reference|task), etc.
Optional fields: tags (list[str], domain/scope format), links (list[str], wikilink titles)

### Reference
Same table format — differences from Note highlighted

### Task
Same table format — task-specific fields (status transitions)

### Session (Log)
Same table format

## Lifecycle State Machines

### Note/Reference Lifecycle
```
ACTIVE → REVIEW → DORMANT → ARCHIVED
         ACTIVE ← REVIEW (reject)
```
Show as ASCII state diagram with transition triggers.

### Task Lifecycle
```
ACTIVE → DONE
ACTIVE → BLOCKED → ACTIVE
```

## Constraint Rules

Structured list of hard rules:
- "Garden notes (content_type=note, tags contain garden/*) cannot be closed or archived"
- "Session must be started before session-close"
- "Content type cannot be changed after creation"
- "Tags must match pattern: domain/scope (bare tags emit warning)"
- etc.

Read from domain/types.py and services to extract actual constraints.

## Deterministic Interaction Flows

### Research Capture Flow
Step-by-step with exact CLI commands and MCP tool names:
1. Start session: `ztlctl session start "Research: {topic}"` / MCP: `session_start`
2. Create reference: `ztlctl create reference "{title}" --tags "..."` / MCP: `create_content`
3. Create notes linking references: ...
4. Run reweave: ...
5. Close session: ...

### Knowledge Retrieval Flow
### Session Management Flow

## Input/Output Schemas

### Creating Content — Request
```json
{
  "title": "string (required, 3-200 chars)",
  "content_type": "note | reference | task",
  "body": "string (optional, markdown)",
  "tags": ["domain/scope", ...],
  "links": ["[[Target Title]]", ...]
}
```

### Creating Content — Response
```json
{
  "success": true,
  "data": {"id": "N-0001", "title": "...", ...},
  "meta": {"reweave_suggestions": [...]}
}
```

### Querying — Request/Response schemas

## Error Handling

Table: Error condition, CLI exit code, MCP error format, Recovery action
- "Vault not initialized" → exit 1 → {"error": "..."} → "Run ztlctl init"
- "Note not found" → exit 1 → ... → "Verify ID format"
- etc.

Read actual ServiceResult error patterns from services.
```

Prioritize accuracy over completeness — every schema and constraint must be verified against source code. Use structured data formats (tables, JSON, ASCII diagrams) over prose. Link to mcp.md for full MCP tool catalog rather than duplicating.
  </action>
  <verify>
    <automated>test -f docs/agents.md && wc -l docs/agents.md | awk '{print ($1 >= 300) ? "OK: "$1" lines" : "TOO SHORT: "$1" lines"}'</automated>
  </verify>
  <acceptance_criteria>
    - docs/agents.md exists
    - File is 300-500 lines
    - Contains H2 sections: "System Capabilities", "Entity Schemas", "Lifecycle State Machines", "Constraint Rules", "Deterministic Interaction Flows", "Input/Output Schemas", "Error Handling"
    - Contains at least one ASCII state diagram
    - Contains at least 2 JSON schema blocks
    - Contains at least one structured table with columns
    - Contains link to mcp.md
    - Contains link to agentic-workflows.md
    - First line after H1 mentions "LLM systems" or "AI agents" (audience signal)
    - Does NOT contain tutorial-style prose paragraphs (machine-readable, not human guide)
  </acceptance_criteria>
  <done>agents.md is a 300-500 line machine-readable system manual with entity schemas, state machines, constraint rules, interaction flows, I/O schemas, and error handling — all verified against source code</done>
</task>

</tasks>

<verification>
- `test -f docs/best-practices.md` — file exists
- `test -f docs/agents.md` — file exists
- `wc -l docs/best-practices.md` — 200-350 lines
- `wc -l docs/agents.md` — 300-500 lines
- `grep "Anti-Pattern" docs/best-practices.md` — anti-pattern entries present
- `grep "Entity Schemas" docs/agents.md` — structured schemas present
- `grep "Constraint Rules" docs/agents.md` — constraint rules present
</verification>

<success_criteria>
- best-practices.md exists at 200-350 lines with opinionated anti-pattern/correct-pattern entries and cross-links
- agents.md exists at 300-500 lines with machine-readable schemas, state machines, and deterministic flows
- Both pages serve their distinct audiences without content duplication
- All content is source-verified (not written from memory)
</success_criteria>

<output>
After completion, create `.planning/phases/14-documentation-content-refinement-and-quality-pass/14-02-SUMMARY.md`
</output>
