Skip to content

Backlog and Internal Docs

This page explains the two internal documentation systems that drive day-to-day development in LAV2:

  • Backlog.md for planned work and scope control
  • backlog/docs/ for project-specific internal references

Backlog.md Is The System Of Record

Use Backlog.md for any non-trivial engineering work that needs planning, decision-making, or tracking. In practice this means:

  • Search for an existing task before starting implementation.
  • Create a new task if the work needs design choices or multiple steps.
  • Capture implementation plans, notes, scope changes, and completion status in the task instead of keeping them in ad-hoc chat or scratch files.

Minor mechanical edits do not always need tasks, but real feature work, refactors, and bug investigations do.

Expected Development Flow

  1. Search Backlog before starting.
  2. Move the task to In Progress when you begin.
  3. Record the implementation plan in the task before code changes.
  4. Keep notes in the task as decisions or blockers appear.
  5. Run the relevant checks.
  6. Update acceptance criteria as they are satisfied.

This mirrors the repository's Backlog workflow and keeps the task usable as a handoff record for the next contributor or agent.

How To Read backlog/docs/

The backlog/docs/ directory is not the public documentation site. It stores internal reference notes that are still useful during development.

Treat these files as engineering references. If a workflow becomes part of the normal contributor experience, it should usually be summarized here in docs/ and linked from the public development guide.

Relationship Between Documentation Sources

  • docs/: public-facing, navigable documentation site
  • CONTRIBUTING.md: concise repository-level contribution entrypoint
  • .github/prompts/: prompt-oriented operational guidance for contributors and coding agents
  • backlog/docs/: internal engineering reference material
  • backlog/tasks/: tracked commitments, plans, execution notes, and acceptance criteria

Maintenance Rule

When a development workflow changes, update the source where contributors will actually discover it:

  • Update docs/ for stable contributor-facing guidance.
  • Update .github/prompts/ when the operational prompt used by agents changes.
  • Update backlog/docs/ when the internal engineering reference changes.
  • Update the Backlog task if the change affects current scope or execution.