_ctx-update-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

```text
/_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.

```go
// 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)