Skip to content

refactor(docs): split requirements.md into per-section files under docs/memory/requirements/ #937

Description

@vybe

Summary

`docs/memory/requirements.md` has grown to 2400+ lines covering 36 sections. As a single file it is becoming difficult to navigate, causes merge conflicts when multiple PRs add requirements simultaneously (e.g. #930 and #933 both added §35 in the same session), and makes targeted updates harder to review. Splitting it into per-section files under a `docs/memory/requirements/` directory eliminates the structural conflict surface and gives each capability area a clear owner file.

Context

The conflict on `requirements.md` that surfaced during the #930 / #933 review cycle (both PRs added §35) is a symptom of the file having outgrown the single-file model. The fix is structural: move to a directory where each requirement section lives in its own Markdown file named by its number and slug (e.g. `requirements/35-schedule-timeout-validation.md`), with a lightweight `requirements/README.md` index replacing the current top-of-file table of contents.

Acceptance Criteria

  • `docs/memory/requirements/` directory created; each existing section (§1–§36+) moved to its own file named `-.md`
  • `docs/memory/requirements/README.md` index lists all sections with one-line descriptions and links — replaces the top-level TOC in the old file
  • `docs/memory/requirements.md` either removed or replaced with a redirect stub pointing at the new directory
  • All cross-references to `requirements.md` inside the repo updated to point at the new paths (CLAUDE.md, architecture.md, feature-flows.md, any skill/agent prompts)
  • Development workflow skills updated: any instruction that says "update `docs/memory/requirements.md`" is changed to "add or update the relevant file under `docs/memory/requirements/`"
  • `.claude/` submodule skills that reference requirements location are updated (e.g. `validate-pr`, `implement`, `autoplan`, `cso` prompts)
  • New section convention documented: when a PR adds a new requirement, it creates a new numbered file rather than appending to a monolithic file; numbering convention defined (sequential integers, no gaps)

Technical Notes

  • The `docs/memory/requirements/` path should be added to the `State Dependencies` tables in any skill that reads requirements (validate-pr, implement, autoplan, sprint, cso)
  • Skill prompts that currently read `docs/memory/requirements.md` should be updated to read either the index or the specific section file relevant to the PR under review
  • Consider whether the index `README.md` should be auto-generated from the section files or hand-maintained; hand-maintained is simpler and consistent with the existing docs model
  • Migration can be done in a single PR since it is a pure rename/split — no content changes, just structure

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions