---
phase: 14-documentation-content-refinement-and-quality-pass
plan: 04
type: execute
wave: 2
depends_on: ["14-01"]
files_modified:
  - docs/tutorial.md
  - docs/obsidian.md
  - docs/plugins.md
  - docs/agentic-workflows.md
  - docs/commands.md
autonomous: true
requirements: []

must_haves:
  truths:
    - "Every CLI command example is verified against Click command source code"
    - "Every page has at least 2 concrete real-world examples"
    - "Anti-pattern sections or callouts exist in tutorial, plugins, and agentic-workflows pages"
    - "Cross-links connect related pages (plugins→configuration, agentic→best-practices, tutorial→commands)"
    - "No hedging language in any page"
  artifacts:
    - path: "docs/tutorial.md"
      provides: "Source-verified tutorial with anti-pattern callouts"
      min_lines: 270
    - path: "docs/obsidian.md"
      provides: "Enhanced Obsidian guide with real-world examples"
      min_lines: 160
    - path: "docs/plugins.md"
      provides: "Plugin reference with anti-pattern sections"
      min_lines: 250
    - path: "docs/agentic-workflows.md"
      provides: "Agent workflow guide with anti-pattern section"
      min_lines: 490
    - path: "docs/commands.md"
      provides: "Source-verified command reference"
      min_lines: 160
  key_links:
    - from: "docs/tutorial.md"
      to: "docs/commands.md"
      via: "cross-link for full command reference"
      pattern: "commands"
    - from: "docs/plugins.md"
      to: "docs/configuration.md"
      via: "cross-link for config details"
      pattern: "configuration"
    - from: "docs/agentic-workflows.md"
      to: "docs/best-practices.md"
      via: "cross-link to anti-patterns reference"
      pattern: "best-practices"
---

<objective>
Apply the ThatDev Quality Bar to the five workflow and reference pages in the User Guide. These are the pages users spend the most time with — tutorial, obsidian, plugins, agentic-workflows, and commands. Every CLI example must be source-verified.

Purpose: Ensure the most-used User Guide pages have verified examples, anti-pattern guidance, consistent structure, and cross-links.
Output: Five enhanced documentation pages with source-verified content.
</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: Enhance tutorial.md, obsidian.md, and commands.md</name>
  <files>docs/tutorial.md, docs/obsidian.md, docs/commands.md</files>
  <read_first>
    - docs/tutorial.md (current: 264 lines)
    - docs/obsidian.md (current: 155 lines)
    - docs/commands.md (current: 153 lines)
    - src/ztlctl/commands/create.py (verify create command flags: --tags, --links, --body, --content-type)
    - src/ztlctl/commands/query.py (verify search, get, list, work-queue command flags)
    - src/ztlctl/commands/session_cmd.py (verify session start/close/reopen flags)
    - src/ztlctl/commands/graph.py (verify graph command flags: related, themes, rank, path, gaps, bridges)
    - src/ztlctl/commands/check.py (verify check command flags)
    - src/ztlctl/commands/update.py (verify update command flags)
    - src/ztlctl/commands/export_cmd.py (verify export command flags)
    - src/ztlctl/commands/init_cmd.py (verify init command flags and profiles)
    - src/ztlctl/commands/docs.py (verify docs search command)
  </read_first>
  <action>
Enhance three pages with source-verified content.

**docs/tutorial.md** (target: 270-320 lines, currently 264):
- Read every Click command file referenced in the tutorial and verify every CLI example matches actual flags, argument names, and option names
- Fix any command that doesn't match source (e.g., wrong flag names, missing required args)
- Add 1-2 anti-pattern callout admonitions inline where common mistakes occur (e.g., `!!! warning "Anti-Pattern: Creating notes without tags"`)
- Add or verify "Next Steps" section with cross-links to commands.md, concepts.md, paradigms.md
- Ensure heading hierarchy: H1 title, H2 major workflow steps, H3 subsections
- Eliminate hedging language throughout

**docs/obsidian.md** (target: 160-200 lines, currently 155):
- Verify init --profile obsidian command against init_cmd.py source
- Verify any config options mentioned against models.py
- Add a "Common Pitfalls" section (2-3 entries): sync conflicts, manual DB edits, ignoring .ztlctl directory
- Add cross-links to plugins.md (git plugin for Obsidian), configuration.md
- Ensure 2 concrete examples (e.g., "Setting up for a research vault", "Setting up for a team wiki")

**docs/commands.md** (target: 160-250 lines, currently 153):
- This is the critical verification page — every command, subcommand, and flag must match Click source
- Read each command file in src/ztlctl/commands/ and verify:
  - Command name and group structure
  - All flags (--tag, --type, --limit, etc.) with correct types and defaults
  - Required vs optional arguments
- Add any missing commands (docs search, workflow init/update, vector commands if they exist)
- Use tables for flag reference: Flag, Type, Default, Description
- Add "Global Options" section (--verbose, --log-json, --vault-path if applicable)
- Cross-link to configuration.md for config-based defaults
  </action>
  <verify>
    <automated>wc -l docs/tutorial.md docs/obsidian.md docs/commands.md | tail -1 | awk '{print ($1 >= 590) ? "OK: "$1" total lines" : "TOO SHORT: "$1" total lines"}'</automated>
  </verify>
  <acceptance_criteria>
    - docs/tutorial.md >= 270 lines
    - docs/tutorial.md contains at least 1 `!!! warning` anti-pattern admonition
    - docs/tutorial.md contains "Next Steps" section
    - docs/obsidian.md >= 160 lines
    - docs/obsidian.md contains "Common Pitfalls" or "Troubleshooting" section
    - docs/obsidian.md contains cross-link to plugins.md
    - docs/commands.md >= 160 lines
    - docs/commands.md contains "docs" command entry (for ztlctl docs search)
    - docs/commands.md contains "--verbose" or "--log-json" in global options
    - All CLI flag names match Click source code (verified by reading command files)
  </acceptance_criteria>
  <done>tutorial.md has verified examples and anti-pattern callouts, obsidian.md has pitfalls section, commands.md has source-verified command reference with all commands and flags</done>
</task>

<task type="auto">
  <name>Task 2: Enhance plugins.md and agentic-workflows.md</name>
  <files>docs/plugins.md, docs/agentic-workflows.md</files>
  <read_first>
    - docs/plugins.md (current: 244 lines)
    - docs/agentic-workflows.md (current: 485 lines)
    - src/ztlctl/plugins/hookspecs.py (verify hookspec references in plugins.md)
    - src/ztlctl/plugins/git_plugin.py (verify git plugin behavior descriptions)
    - src/ztlctl/plugins/reweave_plugin.py (verify reweave plugin behavior)
    - src/ztlctl/config/models.py (verify config options mentioned in both pages)
    - src/ztlctl/services/session.py (verify session workflow in agentic-workflows.md)
    - src/ztlctl/services/create.py (verify create pipeline described in workflows)
  </read_first>
  <action>
Enhance the two deepest User Guide pages.

**docs/plugins.md** (target: 250-300 lines, currently 244):
- Verify all git plugin config options against models.py GitConfig class
- Verify all reweave plugin behavior against reweave_plugin.py
- Ensure the `[plugins.git]` TOML section is used (not `[git]`) — should already be correct but verify
- Add anti-pattern section (2-3 entries):
  - Anti-pattern: "Enabling auto_push without reviewing commits first"
  - Anti-pattern: "Setting reweave min_score too low — creates noise"
  - Anti-pattern: "Disabling git plugin after already having git history"
- Add cross-links to configuration.md, best-practices.md
- Ensure 2 concrete scenario examples are present

**docs/agentic-workflows.md** (target: 490-550 lines, currently 485):
- This is already the deepest page — verify, don't rewrite
- Read session.py to verify session lifecycle descriptions
- Read create.py to verify create pipeline descriptions
- Verify every MCP tool name mentioned against mcp/tools.py
- Add anti-pattern section at the end (3-4 entries):
  - Anti-pattern: "Agent creating notes without session context"
  - Anti-pattern: "Agent ignoring ServiceResult.success field"
  - Anti-pattern: "Agent running reweave after every single create (use session close instead)"
  - Anti-pattern: "Agent using raw SQL instead of CLI/MCP tools"
- Add cross-link to best-practices.md and agents.md
- Ensure heading hierarchy consistency
- Eliminate any hedging language
  </action>
  <verify>
    <automated>wc -l docs/plugins.md docs/agentic-workflows.md | tail -1 | awk '{print ($1 >= 740) ? "OK: "$1" total lines" : "TOO SHORT: "$1" total lines"}'</automated>
  </verify>
  <acceptance_criteria>
    - docs/plugins.md >= 250 lines
    - docs/plugins.md contains anti-pattern section or admonitions
    - docs/plugins.md contains cross-link to configuration.md
    - docs/plugins.md uses `[plugins.git]` not `[git]` for TOML config
    - docs/agentic-workflows.md >= 490 lines
    - docs/agentic-workflows.md contains anti-pattern section
    - docs/agentic-workflows.md contains cross-link to best-practices.md or agents.md
    - All MCP tool names in agentic-workflows.md match names in mcp/tools.py
  </acceptance_criteria>
  <done>plugins.md has verified config options, anti-patterns, and cross-links; agentic-workflows.md has verified MCP tool names, anti-pattern section, and cross-links</done>
</task>

</tasks>

<verification>
- All 5 pages have consistent heading hierarchy
- All CLI examples and MCP tool names verified against source
- Anti-pattern sections present in tutorial, plugins, and agentic-workflows
- Cross-links connect related pages
- No hedging language remains
</verification>

<success_criteria>
- tutorial.md has verified CLI examples and anti-pattern callouts
- obsidian.md has pitfalls section and real-world examples
- commands.md has source-verified command/flag reference including all commands
- plugins.md has verified config, anti-patterns, and correct [plugins.git] usage
- agentic-workflows.md has verified MCP tool names and anti-pattern section
</success_criteria>

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