ojhunt-update-env

name: ojhunt-update-env description: Single source of truth for where each piece of knowledge belongs (docs/, ADRs, skills, hooks, commands, CLAUDE.md) and what must NOT be documented because it already lives in code or tests. Load BEFORE writing or editing ANY documentation, ADR, or skill — and whenever choosing where a fact should live or whether to document it at all — not only when explicitly asked to "update docs" or "capture learnings".

Where knowledge lives in this project's environment

Single source of truth: Each piece of knowledge lives in exactly one layer. When adding documentation, point to the authoritative source — don't inline definitions that already exist elsewhere. Duplication causes drift.

Command docs span multiple layers — search before changing. Shell commands (e.g. how to run tests, start the server, add a dependency) can be documented in skills, READMEs, docs/, and referenced inside hook error messages. When a command changes, search all four locations before closing the task: grep -r "the old command" .claude/skills/ README.md docs/ .claude/hooks/

Route between sibling skills, don't append to the most-used one: When adding to a skill, name what the new section is about in one phrase and check whether a sibling ojhunt-* skill owns that phrase. The dominant skill tends to absorb content from neighbouring domains because authors append where they're already editing — resist the easy append.

README.md

Entry-level documentation: setup, usage examples, CLI flags, supported OJs. Update when something operational changes (a command, a new crawler, a setup step).

`docs/` (user-facing)

Documentation for users running or deploying the project:

docs/cli.md — CLI usage reference
docs/web.md — Web UI usage reference
docs/development.md — Crawler contributor guide (__crawler_meta__ fields, login types, templates, return format). Update when the crawler API or contribution process changes.
docs/adr/ — Architectural decisions (see below)

Skills (`.claude/skills/ojhunt-*/`)

Workflow documentation: how to implement crawlers, how to commit, how to write tests, and the conventions behind those workflows. Update when the process of doing something changes in this project — not when the code changes.

Only document what's non-obvious. If Claude can derive it by reading the files, or if it's enforced elsewhere (hook, test, linter), don't write it. Redundant entries create drift.

When a well-written doc file already covers the topic, the skill should be a thin pointer to that file plus any gotchas the doc doesn't capture. Don't replicate discoverable content.

To add a new skill:

Create .claude/skills/ojhunt-<topic>/SKILL.md with frontmatter:

---
name: ojhunt-<topic>
description: <one-line trigger description>
---

Note: Claude Code's skill loader does not support colon-namespaced sub-skills (e.g. ojhunt:topic) at the project level. Each skill must be its own top-level directory. Use the ojhunt- prefix to group related project skills.

Hooks (`.claude/hooks/` + `.claude/settings.json`)

Hard enforcement rules — things the agent must never do or must always do automatically. Update when you need mechanical enforcement, not just reminders. See ojhunt-hooks skill.

Commands (`.claude/commands/`)

Project-level slash commands that override global ones. Create a command when the global equivalent needs project-specific context injected.

Skills can also embed !shell command`` substitutions and $ARGUMENTS directly, so prefer extending an existing skill (e.g. ojhunt-commit owns /commit-style behavior) over adding a parallel command file.

Gotcha when documenting these features in prose: the arguments placeholder gets substituted on render even inside inline-code spans, so writing it literally in skill prose erases it. Describe it ("the arguments placeholder") rather than using the literal token, and reserve the literal token for the section that should actually receive the user's input.

`docs/adr/`

Significant architectural decisions and their rationale. See the ojhunt-commit skill for when a decision warrants an ADR vs a commit message.

To add an ADR: create docs/adr/NNNN-short-title.md and add a one-line pointer to the ADR list in docs/development.md.

`CLAUDE.md`

Context that every agent working on this project must know, regardless of the task. Update when something is so fundamental that any agent — without it — would make the wrong call: project-wide invariants, hard constraints, or pointers to where documentation lives.

Keep entries minimal. CLAUDE.md is loaded into every conversation; bloat here costs context on every invocation. If the knowledge is task-specific (e.g., "how to write a crawler"), put it in a skill, not here.

If unsure which layer

Operational fact (setup, command, structure) → README
User-facing reference → docs/
Crawler contributor reference → docs/development.md
Workflow or process → .claude/skills/ojhunt-*/
"Never do X" or "always do Y after Z" → hook first (see ojhunt-hooks skill); once hook-enforced, do NOT also add a skill entry — the hook is the enforcement, a skill note just creates drift
Project-level command override → .claude/commands/
Significant architectural decision (multiple approaches considered, choice non-obvious from code) → docs/adr/
Small tactical change → commit message intent (no doc needed)
Project-wide invariant every agent must know, regardless of task → CLAUDE.md

Capturing session learnings

When the user asks to capture session learnings (e.g. "what did we learn", "update the docs"), follow this flow. The first two steps are silent — only start outputting at step 3.

Step 1 (silent): Reflect

Identify what was non-obvious, missing, or corrected that would help future sessions:

Workflows, conventions, or gotchas not yet documented
Feedback or corrections from the user on how to approach work
Project state changes: features shipped, decisions made, bugs resolved

Step 2 (silent): Route changes

Use the routing rules above to decide where each learning belongs. Do not route from memory — re-read the relevant section if unsure.

Step 3: Show proposed changes

For each learning, show the target file and a concise diff. Keep additions brief — skill files are loaded into every prompt.

Step 4: Apply with approval

Ask the user which changes to apply. Only edit the files they approve.

Important: Documentation updates (skill files, README, docs/) are the primary output — always propose at least one. Memory updates are optional and secondary; never substitute memory for documentation.