design-program

Design Program

Translate the supplied story and target architecture into an exact, maintainable program design grounded in the existing codebase. Treat the story as immutable product scope, use the current-state and architecture artifacts as working engineering context, and write the complete design at the requested path so implementation planning can organize the work without inventing consequential contracts, representations, behavior, or code structure.

Specify every decision whose alternatives could materially affect contracts, maintainability, behavior, or testability. Leave locally interchangeable implementation details open.

Artifact Contract

Cover the following knowledge in the form that best fits the system and story:

• Design basis and resolved target: Identify the story and predecessor artifacts, state the concrete program-level result, and distinguish verified repository facts, inherited architecture decisions, and proposed program-design choices. Preserve the architecture's intended system shape while resolving the code-level decisions it deliberately deferred.
• Program structure and collaboration: Define the load-bearing module layout, responsibilities, dependencies, and placement of new behavior. Name exact repository homes and important existing or proposed symbols. Explain consequential additions, removals, moves, and reuse, and trace important entry points through their collaborators to observable results. Use compact file-tree or call-path views when they make layout or control flow easier to inspect.
• Contracts and representations: Define exact changed external and cross-module contracts, including applicable APIs, routes, events, schemas, queries, persisted representations, configuration, and wire formats. Define consequential internal types and function or method signatures. State identity, ownership, lifetime, optionality, mutability, validation, preconditions, postconditions, and representation invariants where they affect correctness. When a boundary changes, turn the architecture's compatibility policy into concrete compatibility and migration mechanics.
• Behavioral mechanics: Specify the detailed success and failure paths, state transitions, data transformations, and component collaboration. Settle ordering, concurrency, transaction boundaries, idempotency, cancellation, timeout, retry, stale-data, and partial-failure behavior when relevant. For user-interface work, define consequential interaction states, focus and keyboard behavior, accessibility semantics, and recovery. Use examples, state tables, sequence descriptions, or focused pseudocode where they remove material ambiguity.
• Verification and operability design: Identify test seams, scenario classes, important fixtures, invariants, and observable outcomes. Connect consequential edge cases to the level of testing that can establish them. Define logging, metrics, diagnostics, or audit behavior when the change needs operational evidence. Describe what must be verifiable without assigning checks to implementation phases.
• Traceability and remaining risk: Account for every story outcome and relevant architecture decision. Connect each to its concrete code owner, contracts, flows, failure behavior, and verification seam. Converge on one recommended program design. For material uncertainty, select and justify an assumption, state the consequence if it is wrong, and explain how downstream work can verify it.