ctx-update-docs

name	_ctx-update-docs
description	Check if docs and code conventions are consistent after changes. Use after modifying source code, before committing, or when asked to sync docs.

When source code changes, check public docs AND internal code conventions for consistency.

When to Use

• After modifying source code that has user-facing behavior
• Before committing changes that touch CLI flags, file formats, or defaults
• When the user asks to sync docs with code
• After adding or removing commands, subcommands, or flags

When NOT to Use

• When changes are purely internal — renaming a private variable, reordering unexported code — skip this skill and commit directly
• When only docs were changed (no code to drift from)
• When the user explicitly says docs updates are not needed

Usage Examples

/_ctx-update-docs
/_ctx-update-docs (after adding --session flag to ctx agent)

Workflow

1. Diff the branch: git diff main --stat (or relevant base)
2. Verify mapping is current (see Self-Maintenance below)
3. Map changed packages to affected docs (see table)
4. Read each affected doc; flag sections that contradict the new code
5. Update or flag for the user
6. Validate: mkdocs build in docs site (if available)

Code-to-Docs Mapping

Source Path	Likely Affected Docs
cmd/ctx/, internal/cli/	docs/cli/*.md
internal/config/	docs/home/context-files.md, docs/home/configuration.md
internal/context/	docs/home/context-files.md, docs/home/prompting-guide.md
internal/drift/	docs/recipes/context-health.md
internal/journal/	docs/reference/session-journal.md, docs/cli/journal.md
internal/bootstrap/	docs/home/getting-started.md
internal/claude/, internal/rc/	docs/operations/integrations.md, docs/home/configuration.md
internal/assets/	docs/home/context-files.md (templates)
internal/assets/claude/skills/	.claude/skills/ (live versions), docs/reference/skills.md
SECURITY.md	docs/security/*.md
.context/ schema changes	docs/home/context-files.md

What to Check

• New CLI flags/commands: are they in docs/cli-reference.md?
• Changed file formats: does docs/context-files.md match?
• New context files: added to both read order docs and docs/context-files.md?
• Removed features: still referenced in docs?
• Changed defaults: do examples in docs use old defaults?
• Skill templates changed: do live versions in .claude/skills/ match internal/assets/claude/skills/?
• Architecture drift: when packages are added, removed, or renamed, or when dependency relationships change, update .context/ARCHITECTURE.md (component map, dependency graph, and file layout sections). ctx drift scans ARCHITECTURE.md for dead backtick-path references.

Self-Maintenance

This mapping table will drift. Before relying on it:

1. ls internal/: any packages not in the table? Add them.
2. ls docs/*.md: any doc pages not in the table? Map them.
3. If the mapping table is stale, flag it to the user rather than editing this file automatically.

The skill is its own first test case: if the mapping is stale, the skill has already failed at its job.

Internal Code Conventions

Also check that changed code follows project patterns (not Go defaults):

Godoc Style

Project uses explicit Parameters/Returns sections, not standard godoc.

// Good (project style):
// FunctionName does X.
//
// Parameters:
//   - param1: Description
//
// Returns:
//   - Type: Description
func FunctionName(param1 string) error

// Bad (standard godoc; agent corpus drift):
// FunctionName does X with param1.
func FunctionName(param1 string) error

Verify that godoc comments match actual parameters and behavior.

Predicate Naming

Project uses predicates without Is/Has/Can prefixes:

• Completed() not IsCompleted()
• Empty() not IsEmpty()
• Exists() not DoesExist()

File Organization

Public API in the main file, private helpers in separate logical files:

• loader.go (public Load()) + process.go (private)
• NOT: everything in one file with unexported functions at the bottom

Magic Strings

Literals belong in internal/config/. If you see a hardcoded string used in 2+ files, it needs a constant. Check internal/config/ for existing constants before introducing new literals.

Relationship to ctx drift

ctx drift checks .context/ file health (dead paths, staleness). This skill checks docs-to-source-code alignment and internal conventions. They are complementary.

Quality Checklist

Before reporting results, verify:

• All changed packages were mapped to their affected docs
• Each flagged doc section was actually read (not assumed)
• Skill template/live drift was checked if internal/assets/ was touched
• Self-maintenance was done (mapping table is current)