docs: standardize Go docstrings with Parameters/Returns/Fields sections

Go documentation fixes:
- Add Fields blocks to structs (addFlags, EntryParams, IndexEntry, TaskBlock,
  fixResult, ContextUpdate, Session, Message)
- Add Parameters/Returns to functions (ParseDecisionHeaders, GenerateIndex,
  UpdateIndex, UpdateLearningsIndex, UncheckedTaskPattern, GetIndentLevel,
  RemoveBlocksFromLines, SetContextDir, ContextDir)
- Preserve taxonomy groupings in Session struct Fields block
- Remove redundant inline comments where Fields block exists
- Add Flags/Returns to watch.Cmd()

Agent guidance:
- Add Go Documentation Standard section to AGENT_PLAYBOOK.md
- Add learning: documentation audits require verification against standards
- Update template AGENT_PLAYBOOK.md for new projects

Signed-off-by: Jose Alekhinne <alekhinejose@gmail.com>

Author: josealekhine

.context/AGENT_PLAYBOOK.md

@@ -359,3 +359,73 @@ Never assume: If you don't see it in files, you don't know it.
 - Don't invent history - check sessions/ for actual discussions
 - If uncertain, say "I don't see this documented"
 - Trust files over intuition
+
+## Go Documentation Standard
+
+When writing Go code, follow this docstring format consistently.
+
+### Functions
+
+```go
+// FunctionName does X.
+//
+// Extended description if needed.
+//
+// Parameters:
+//   - param1: Description of first parameter
+//   - param2: Description of second parameter
+//
+// Returns:
+//   - ReturnType: Description of return value
+//   - error: When this error occurs
+func FunctionName(param1 Type1, param2 Type2) (ReturnType, error) {
+```
+
+### Structs
+
+```go
+// StructName represents X.
+//
+// Extended description if needed.
+//
+// Fields:
+//   - Field1: Description of field
+//   - Field2: Description of field
+type StructName struct {
+    Field1 Type1
+    Field2 Type2
+}
+```
+
+### Struct Fields with Taxonomy
+
+For complex structs, group related fields:
+
+```go
+// Session represents a conversation session.
+//
+// Fields:
+//
+// Identity:
+//   - ID: Unique session identifier
+//   - Slug: URL-friendly identifier
+//
+// Timing:
+//   - StartTime: When the session started
+//   - EndTime: When the session ended
+type Session struct {
+    ID        string
+    Slug      string
+
+    StartTime time.Time
+    EndTime   time.Time
+}
+```
+
+### Reference Examples
+
+Before writing new code, check these well-documented files:
+- `internal/cli/status/types.go` — struct documentation
+- `internal/claude/types.go` — structs with Fields sections
+- `internal/drift/detector.go` — functions with Parameters/Returns
+- `internal/context/loader.go` — complete function documentation

.context/LEARNINGS.md

@@ -1,44 +1,55 @@
 # Learnings
 
 <!-- INDEX:START -->
-| Date       | Learning                                             |
-|------------|------------------------------------------------------|
-| 2026-01-28 | Required flags now enforced for learnings            |
-| 2026-01-28 | Claude Code Hooks Receive JSON via Stdin             |
-| 2026-01-28 | Changelogs vs Blogs serve different audiences        |
-| 2026-01-28 | IDE is already the UI                                |
+| Date | Learning |
+|------|--------|
+| 2026-01-29 | Documentation audits require verification against actual standards |
+| 2026-01-28 | Required flags now enforced for learnings |
+| 2026-01-28 | Claude Code Hooks Receive JSON via Stdin |
+| 2026-01-28 | Changelogs vs Blogs serve different audiences |
+| 2026-01-28 | IDE is already the UI |
 | 2026-01-28 | Subtasks complete does not mean parent task complete |
-| 2026-01-28 | AI session JSONL formats are not standardized        |
-| 2026-01-27 | Always Complete Decision Record Sections             |
-| 2026-01-27 | Slash Commands Require Matching Permissions          |
-| 2026-01-26 | Go json.Marshal Escapes Shell Characters             |
-| 2026-01-26 | Claude Code Hook Key Names                           |
-| 2026-01-25 | defer os.Chdir Fails errcheck Linter                 |
-| 2026-01-25 | golangci-lint Go Version Mismatch in CI              |
-| 2026-01-25 | CI Tests Need CTX_SKIP_PATH_CHECK                    |
-| 2026-01-25 | AGENTS.md Is Not Auto-Loaded                         |
-| 2026-01-25 | Hook Regex Can Overfit                               |
-| 2026-01-25 | Autonomous Mode Creates Technical Debt               |
-| 2026-01-23 | ctx agent vs Manual File Reading Trade-offs          |
-| 2026-01-23 | Claude Code Skills Format                            |
-| 2026-01-23 | Infer Intent on "Do You Remember?" Questions         |
-| 2026-01-23 | Always Use ctx from PATH                             |
-| 2026-01-21 | Exit Criteria Must Include Verification              |
-| 2026-01-21 | Orchestrator vs Agent Tasks Must Be Separate         |
-| 2026-01-21 | One Templates Directory, Not Two                     |
-| 2026-01-21 | Hooks Should Use PATH, Not Hardcoded Paths           |
-| 2026-01-20 | ctx and Ralph Loop Are Separate Systems              |
-| 2026-01-20 | .context/ Is NOT a Claude Code Primitive             |
-| 2026-01-20 | SessionEnd Hook Catches Ctrl+C                       |
-| 2026-01-20 | Session Filename Must Include Time                   |
-| 2026-01-20 | Two Tiers of Persistence                             |
-| 2026-01-20 | Auto-Load Works, Auto-Save Was Missing               |
-| 2026-01-20 | Always Backup Before Modifying User Files            |
-| 2026-01-19 | CGO Must Be Disabled for ARM64 Linux                 |
+| 2026-01-28 | AI session JSONL formats are not standardized |
+| 2026-01-27 | Always Complete Decision Record Sections |
+| 2026-01-27 | Slash Commands Require Matching Permissions |
+| 2026-01-26 | Go json.Marshal Escapes Shell Characters |
+| 2026-01-26 | Claude Code Hook Key Names |
+| 2026-01-25 | defer os.Chdir Fails errcheck Linter |
+| 2026-01-25 | golangci-lint Go Version Mismatch in CI |
+| 2026-01-25 | CI Tests Need CTX_SKIP_PATH_CHECK |
+| 2026-01-25 | AGENTS.md Is Not Auto-Loaded |
+| 2026-01-25 | Hook Regex Can Overfit |
+| 2026-01-25 | Autonomous Mode Creates Technical Debt |
+| 2026-01-23 | ctx agent vs Manual File Reading Trade-offs |
+| 2026-01-23 | Claude Code Skills Format |
+| 2026-01-23 | Infer Intent on "Do You Remember?" Questions |
+| 2026-01-23 | Always Use ctx from PATH |
+| 2026-01-21 | Exit Criteria Must Include Verification |
+| 2026-01-21 | Orchestrator vs Agent Tasks Must Be Separate |
+| 2026-01-21 | One Templates Directory, Not Two |
+| 2026-01-21 | Hooks Should Use PATH, Not Hardcoded Paths |
+| 2026-01-20 | ctx and Ralph Loop Are Separate Systems |
+| 2026-01-20 | .context/ Is NOT a Claude Code Primitive |
+| 2026-01-20 | SessionEnd Hook Catches Ctrl+C |
+| 2026-01-20 | Session Filename Must Include Time |
+| 2026-01-20 | Two Tiers of Persistence |
+| 2026-01-20 | Auto-Load Works, Auto-Save Was Missing |
+| 2026-01-20 | Always Backup Before Modifying User Files |
+| 2026-01-19 | CGO Must Be Disabled for ARM64 Linux |
 <!-- INDEX:END -->
 
 ---
 
+## [2026-01-29-164322] Documentation audits require verification against actual standards
+
+**Context**: Agent claimed 'no Go docstring issues found' but manual inspection revealed many functions missing Parameters/Returns sections. The agent only checked if comments existed, not if they followed the standard format.
+
+**Lesson**: When auditing documentation, compare against a known-good example first. Pattern-match for the COMPLETE standard (e.g., '// Parameters:' AND '// Returns:' sections), not just presence of any comment.
+
+**Application**: Before declaring 'no issues', manually verify at least 5 random samples match the documented standard. Use grep patterns that detect missing sections, not just missing comments.
+
+---
+
 ## [2026-01-28-191951] Required flags now enforced for learnings
 
 **Context**: Implemented ctx add learning flags to match decision's ADR (Architectural Decision Record) pattern

internal/cli/add/add.go

@@ -127,6 +127,16 @@ Examples:
 }
 
 // addFlags holds all flags for the add command.
+//
+// Fields:
+//   - priority: Priority level for tasks (high, medium, low)
+//   - section: Target section in TASKS.md
+//   - fromFile: Read content from file instead of argument
+//   - context: Context field for decisions/learnings
+//   - rationale: Rationale field for decisions
+//   - consequences: Consequences field for decisions
+//   - lesson: Lesson field for learnings
+//   - application: Application field for learnings
 type addFlags struct {
 	priority     string
 	section      string

internal/cli/add/index.go

@@ -18,10 +18,15 @@ const (
 )
 
 // IndexEntry represents a parsed entry header from a context file.
+//
+// Fields:
+//   - Timestamp: Full timestamp (YYYY-MM-DD-HHMMSS)
+//   - Date: Date only (YYYY-MM-DD)
+//   - Title: Entry title
 type IndexEntry struct {
-	Timestamp string // Full timestamp: YYYY-MM-DD-HHMMSS
-	Date      string // Date only: YYYY-MM-DD
-	Title     string // Entry title
+	Timestamp string
+	Date      string
+	Title     string
 }
 
 // DecisionEntry is an alias for backward compatibility.
@@ -61,6 +66,12 @@ func ParseEntryHeaders(content string) []IndexEntry {
 }
 
 // ParseDecisionHeaders is an alias for ParseEntryHeaders for backward compatibility.
+//
+// Parameters:
+//   - content: The full content of a context file
+//
+// Returns:
+//   - []DecisionEntry: Slice of parsed entries (may be empty)
 func ParseDecisionHeaders(content string) []DecisionEntry {
 	return ParseEntryHeaders(content)
 }
@@ -103,6 +114,12 @@ func GenerateIndexTable(entries []IndexEntry, columnHeader string) string {
 }
 
 // GenerateIndex creates a markdown table for decisions (backward compatibility).
+//
+// Parameters:
+//   - entries: Slice of decision entries to include
+//
+// Returns:
+//   - string: Markdown table or empty string if no entries
 func GenerateIndex(entries []DecisionEntry) string {
 	return GenerateIndexTable(entries, "Decision")
 }
@@ -182,11 +199,23 @@ func updateFileIndex(content, fileHeader, columnHeader string) string {
 }
 
 // UpdateIndex regenerates the decision index in DECISIONS.md content.
+//
+// Parameters:
+//   - content: The full content of DECISIONS.md
+//
+// Returns:
+//   - string: Updated content with regenerated index
 func UpdateIndex(content string) string {
 	return updateFileIndex(content, "# Decisions", "Decision")
 }
 
 // UpdateLearningsIndex regenerates the learning index in LEARNINGS.md content.
+//
+// Parameters:
+//   - content: The full content of LEARNINGS.md
+//
+// Returns:
+//   - string: Updated content with regenerated index
 func UpdateLearningsIndex(content string) string {
 	return updateFileIndex(content, "# Learnings", "Learning")
 }

internal/cli/add/run.go

@@ -20,21 +20,36 @@ import (
 )
 
 // EntryParams contains all parameters needed to add an entry to a context file.
+//
+// Fields:
+//   - Type: Entry type (decision, learning, task, convention)
+//   - Content: Title or main content
+//   - Section: Target section (for tasks)
+//   - Priority: Priority level (for tasks)
+//   - Context: Context field (for decisions/learnings)
+//   - Rationale: Rationale (for decisions)
+//   - Consequences: Consequences (for decisions)
+//   - Lesson: Lesson (for learnings)
+//   - Application: Application (for learnings)
 type EntryParams struct {
-	Type         string // decision, learning, task, convention
-	Content      string // Title or main content
-	Section      string // Target section (for tasks)
-	Priority     string // Priority level (for tasks)
-	Context      string // Context field (for decisions/learnings)
-	Rationale    string // Rationale (for decisions)
-	Consequences string // Consequences (for decisions)
-	Lesson       string // Lesson (for learnings)
-	Application  string // Application (for learnings)
+	Type         string
+	Content      string
+	Section      string
+	Priority     string
+	Context      string
+	Rationale    string
+	Consequences string
+	Lesson       string
+	Application  string
 }
 
 // ValidateEntry checks that required fields are present for the given entry type.
 //
-// Returns an error with details about missing fields, or nil if valid.
+// Parameters:
+//   - params: Entry parameters to validate
+//
+// Returns:
+//   - error: Non-nil with details about missing fields, nil if valid
 func ValidateEntry(params EntryParams) error {
 	fType := strings.ToLower(params.Type)