| name | requirements |
| description | Turns a feature request into a full implementation-plan requirements document matching docs/plan/_TEMPLATE.md. Use when the user asks for requirements, a spec, an implementation plan, or wants to flesh out a feature before building. Also use for /requirements or "write requirements for X". |
| disable-model-invocation | true |
Requirements
Turn a user request into a complete Lextures implementation plan — the same structure and rigor as docs/plan/.
Output
Produce a markdown document that follows docs/plan/_TEMPLATE.md exactly. Every section must be filled; no … or TBD placeholders unless listed explicitly in Open Questions (§18).
Default: paste the full document in chat. If the user asks to save it, write to docs/plan/{section-folder}/{id}-{kebab-slug}.md per docs/plan/README.md conventions.
Workflow
Copy this checklist and track progress:
Requirements progress:
- [ ] Step 1: Parse the request
- [ ] Step 2: Explore codebase & existing plans
- [ ] Step 3: Draft metadata
- [ ] Step 4: Write all 19 sections
- [ ] Step 5: Validate against checklist
Step 1. Parse the request
Extract from the user's message:
- Feature name — short, descriptive title
- Scope — what they want; what they explicitly excluded
- Audience — K12 / HE / SL (self-learner) / platform-wide
- Urgency signals — blocker vs enhancement, pilot vs GA
If critical details are missing (audience, scope boundary, or whether this is net-new vs extending existing behavior), ask one focused question before proceeding. Otherwise state your interpretation briefly and continue.
Step 2. Explore codebase & existing plans
Before writing requirements, ground the spec in what exists:
- Read
docs/plan/_TEMPLATE.md for the canonical section list.
- Search
docs/plan/ for related plans — read 1–2 closest matches for tone, cross-references, and dependency patterns.
- Search
docs/completed/ if the feature may partially exist.
- Explore the codebase — Glob/Grep/Read for:
- Existing routes, services, DB tables, UI pages that overlap
- Patterns to extend (auth scopes, job queue, feature flags, migrations)
- File paths to cite in §19 References
Record findings: what is MISSING, PARTIAL, or THIN today (for metadata Status).
Step 3. Draft metadata
Fill the metadata table. Propose values when the user did not supply them:
| Field | Guidance |
|---|
| Feature ID | {section}.{number} — match an existing docs/plan/ section when possible; otherwise propose next number in the closest section |
| Section | Top-level plan folder name (e.g. Platform, Performance & Operability) |
| Severity | BLOCKER / MAJOR / MINOR per docs/plan/README.md legend |
| Markets | K12 / HE / SL — comma-separated |
| Status (today) | MISSING / PARTIAL / THIN based on codebase exploration |
| Estimated effort | XS / S / M / L / XL |
| Depends on / Unblocks | Feature IDs from related plans; use relative links |
Title line format:
# {Feature ID} — {Feature Name}
> Implementation plan. Source: user request / {related doc if any}.
Step 4. Write all 19 sections
Follow the template section-by-section. Quality bar matches completed plans like 17.14-feature-flags.md and 19.3-ai-assisted-grading.md.
§1 Problem Statement — 2–4 sentences. Gap today, who is hurt, business outcome.
§2 Goals — 3–5 outcome bullets. Verifiable, not implementation steps.
§3 Non-Goals — Explicit out-of-scope items. Reference other Feature IDs when deferring work.
§4 Personas & User Stories — As a {role}, I want … so that …. Cover student, instructor, admin, and self-learner where relevant.
§5 Functional Requirements — Numbered FR-N. RFC 2119: MUST / SHOULD / MAY. Testable, not vague.
§6 Non-Functional Requirements — Cover applicable sub-bullets from the template (performance, security, privacy, a11y, scalability, reliability, observability, maintainability, i18n, backward compatibility). Omit sub-bullets that genuinely do not apply; say "N/A" with one-line rationale.
§7 Acceptance Criteria — Numbered AC-N. Given/When/Then. Each AC should map to at least one test.
§8 Data Model — SQL or schema description. Migration naming: server/migrations/NNN_*.sql. Indexes, constraints, backfill strategy.
§9 API Surface — Table or list: method, path, auth scope, request/response shapes. Note rate limits and OpenAPI updates.
§10 UI / UX — Pages, components, flows, empty/loading/error states, responsive behavior, a11y notes, i18n keys.
§11 AI / ML Considerations — Skip entirely (write "N/A — not AI-touching.") only when the feature has zero AI/LLM/ML involvement. Otherwise: models, prompts, eval metrics, fallback, PII, cost budget.
§12 Integration Points — External services and internal modules with file paths.
§13 Dependencies & Sequencing — Must ship after/before; shared infra (Redis, job queue, object storage, etc.).
§14 Risks & Mitigations — Table: Risk | Likelihood | Impact | Mitigation.
§15 Rollout Plan — Feature flag name, phases, pilot cohort, GA criteria, rollback path.
§16 Test Plan — Unit, integration, e2e (Playwright), security, accessibility (axe), performance/load, manual QA.
§17 Documentation & Training — User docs, admin docs, API reference, runbooks.
§18 Open Questions — Numbered decisions still needing owners. Only place for unresolved TBDs.
§19 References — Existing code paths (server/internal/..., clients/web/src/...), external standards, related plans as relative links.
Lextures-specific defaults
When the spec touches these areas, align with repo conventions (see AGENTS.md):
- Backend: Go API, Chi router, pgx, JWT auth,
server/internal/
- Frontend: React 19, Vite, TypeScript, Tailwind v4,
clients/web/src/
- Migrations:
server/migrations/NNN_descriptive_name.sql
- Auth: Note JWT scope and role checks on every new route
- Jobs: Background work via RabbitMQ queue (or in-process fallback locally)
- Feature flags: Reference OpenFeature-style flags and
platformstate when rollout-sensitive
- Compliance: FERPA for student data; WCAG 2.1 AA for new UI; COPPA for K12 minors
Step 5. Validate
Before delivering, verify every item in references/checklist.md. Fix gaps before presenting.
Delivery format
Present the document in this order:
- Summary (3–5 bullets) — what the feature does, severity, effort, key dependencies
- Full requirements document — complete markdown, all 19 sections
- Suggested next steps — only if useful: save path, related plans to read, open questions needing user input
Examples
User: "Write requirements for instructor bulk email to enrolled students"
Agent: Explores server/internal/ for messaging/email modules and docs/plan/06-communication-collaboration/. Produces a full 19-section plan with FRs for opt-out compliance, rate limits, and audit logging.
User: "Requirements for adding dark mode to the student dashboard"
Agent: Finds existing theme/CSS variables in clients/web/. Status = PARTIAL if theme tokens exist. Non-goals reference system-preference-only scope. ACs cover persistence, contrast ratios, and no flash on load.
Additional resources
