Changelog & Troubleshooting (Agent Conventions)

Full conventions for the project/changelog/ and project/troubleshooting/ directory systems, "update the logs" behavior, and plans (README + TODO). Changelog merges change entries and completed plans (one index).

Changelog System (project/changelog/ directory)

  • When to create changelog entries: For any code change (features, fixes, refactors, docs, config). One file per change. Also use for completed plans: move plan doc to project/changelog/plans/ with date prefix and add a row to the same index with Type=plan.
  • Location: Use the project/changelog/ directory. Do NOT use a single CHANGELOG.md file at root or in content/.
  • Structure:
  • Type folders: added/, changed/, fixed/, improved/, docs/, refactor/, config/ for short change entries.
  • plans/ subdir for completed/archived full plan documents (date-prefixed filenames).
  • Single index: project/changelog/index.md — columns Date | Type | Title | File | Notes. Types include the above plus plan for archived plans.
  • File naming for changes: <yyyy-mm-dd>-<type>-<short-title>.md; for plans: yyyy-mm-dd-<plan-name>.md in project/changelog/plans/.
  • Index maintenance: Always update project/changelog/index.md when adding a change entry or archiving a plan (add row at the top of the table).
  • Template: See project/changelog/README.md for the entry template and full conventions.

Troubleshooting System (project/troubleshooting/ directory)

  • When to create troubleshooting entries: Document bugs, issues, or non-trivial problems that required investigation and resolution.
  • Bugs: Any defect that causes incorrect behavior or crashes
  • Issues: Problems that required debugging, investigation, or workarounds
  • Non-trivial problems: Issues that took significant time to resolve, involved multiple steps, or have lessons worth preserving (e.g., complex configuration issues, unexpected framework behavior, tricky debugging scenarios)
  • When NOT to create troubleshooting entries: Simple code changes, routine refactoring, or straightforward feature additions that don't involve problem-solving. Changelog only for those.
  • Location: Use the project/troubleshooting/ directory. Do NOT create individual entries in TROUBLESHOOTING.md or content/TROUBLESHOOTING.md.
  • Structure:
  • Create individual files in the appropriate category folder (build/, runtime/, data/, environment/, security/)
  • File naming: <yyyy-mm-dd>-<category>-<short-title>.md
  • Each entry must include: Date, Category, Status, Symptom, Root Cause, Fix, Verification, Notes/Lessons
  • Index maintenance: Always update project/troubleshooting/index.md when adding a new entry (add row at the top of the table).
  • Template: See project/troubleshooting/README.md for the entry template and full conventions.

Note about content/TROUBLESHOOTING.md: If this file exists, it serves as a user-facing troubleshooting guide with common error states and solutions. It is maintained separately from the project/troubleshooting/ directory system. Individual troubleshooting entries should go in project/troubleshooting/, not in content/TROUBLESHOOTING.md.

Interpreting "Update the Logs"

When instructed to "update the logs" or "update the log files", this refers to:

  1. Changelog – Create a new entry in project/changelog/<type>/<yyyy-mm-dd>-<type>-<short-title>.md and add a row at the top of project/changelog/index.md. Use the appropriate type folder (added, changed, fixed, improved, docs, refactor, config). For a completed plan, move the plan to project/changelog/plans/ with date prefix and add a row with Type=plan. See project/changelog/README.md for the template.
  2. Troubleshooting entries – Add entries to project/troubleshooting/ only when the work involved fixing a bug, resolving an issue that required debugging/workarounds, or solving a non-trivial problem (investigation, multiple steps, or lessons worth preserving). Do not add troubleshooting entries for simple code changes, routine refactors, or straightforward feature additions — use the changelog only for those.
  3. Both – When a bug/issue/non-trivial fix requires both a troubleshooting entry (for the problem-solving process) and a changelog entry (for the change itself).

Note: This project does NOT use application logging files (.log files). The "logs" refer to the project/changelog/ directory and the troubleshooting knowledge base in project/troubleshooting/.

Completed plans – filing rule (operating rule)

When a plan is completed, or the user asks to "file" or "move to changelog" a plan:

  1. Move the plan (file or directory) from project/plans/ or project/build/ to project/changelog/plans/.
  2. Naming: If the plan name does not already start with yyyy-mm-dd-, prepend the date (e.g. 2026-03-08-my-plan). Directories keep their name; single files become yyyy-mm-dd-<name>.md in project/changelog/plans/.
  3. Index: Add a new row at the top of project/changelog/index.md with:
  4. Date: YYYY-MM-DD
  5. Type: plan
  6. Title: Short descriptive title (e.g. "LM Studio integration plan")
  7. File: Path relative to project/changelog/, e.g. plans/2026-03-08-my-plan/ for a directory or plans/2026-03-08-my-plan.md for a single file.

Optional: add a docs changelog entry recording that the plan was moved (e.g. "Plan X moved to changelog/plans") and add a docs row to the same index.

See project/changelog/plans/README.md for naming and index conventions.

Documentation, Plans & Project Directories

  • Changelog: project/changelog/ — one index for change entries and completed plans (type folders + plans/ subdir). Always update project/changelog/index.md (new row at top).
  • Troubleshooting: project/troubleshooting/ — one file per issue in category folders; always update project/troubleshooting/index.md (new row at top).
  • Docs: content/ holds project documentation; content/agents/ holds agent-facing detailed guides. Root AGENTS.md stays slim and links to content/agents/.
  • Plans: project/plans/README.md is a map to the project dir (KIV, research, build, changelog, troubleshooting). project/plans/TODO.md holds current tasks and is kept up to date. Active plan documents live in project/plans/ or project/build/. Completed plans must be filed in project/changelog/plans/ with date prefix and a row in project/changelog/index.md (Type=plan) — see § Completed plans – filing rule above.