references/design_doc.md

GitHub

[Feature/Project Name]

  • Author: [Author Name or GitHub Handle]
  • Status: [Draft | Proposed | In Review | Approved]
  • Date: [YYYY-MM-DD]

Overview

The Problem

[Summarize the problem and the proposed solution here.]

Goals

  • Goal 1
  • Goal 2

Non-Goals

  • Non-Goal 1
  • Non-Goal 2

Open Questions

  • Question 1: [Description of technical unknown or open question]
  • Question 2: [Description of technical unknown or open question]

Critical User Journeys (CUJs)

CUJ 1: [Journey Title]

  • Given: [Preconditions]
  • When: [Actions]
  • Then: [Expected Outcomes]

CUJ 2: [Journey Title]

  • Given: [Preconditions]
  • When: [Actions]
  • Then: [Expected Outcomes]

Technical Plan (Architecture)

[Explain your architectural choices, data structures, and system component mapping here.]

[Optional ASCII Architecture Diagram]

Alternatives Considered

Alternative A: [Alternative Title]

  • Pros: [List benefits]
  • Cons: [List drawbacks]
  • Reason for Rejection: [Why this option was not selected]

Non-Functional Requirements

[Detail any critical non-functional requirements here. If none are critical, this section can be omitted or stated as "None".]


Additional Resources

  • Important project docs referenced
  • Important docs/ referenced
  • Related work

Future Improvements

  • The idea: What could be improved?

Detailed Implementation Plan

Target Files to Create/Modify

1. [File Path 1] ([Create | Modify])

  • Type / Scope: [e.g., Python Service, C++ Library, TypeScript Module, Build Configuration]
  • Proposed Changes: [Describe the new APIs, class/function signatures, or behavioral logic here. Focus on the minimal required details for implementation.]

2. [File Path 2] ([Create | Modify])

  • Type / Scope: [e.g., Unit Test, E2E Test Driver]
  • Proposed Changes: [Describe the test coverage, expected test cases, or mock assertions.]

Verification Plan

  • Compilation/Build: [e.g., npm run build, cargo build, make]
  • Unit Tests: [e.g., pytest, npm test, cargo test]
  • Static Analysis & Linting: [e.g., eslint, ruff check, golangci-lint]
  • Test Coverage Requirement: [e.g., 85%+ branch coverage]
  • E2E/Integration: [e.g., Integration test command or automated eval runner]

Drafted with EGM