02 Low Level Design

Low-Level Design Skill

Use When

• A component boundary and its requirements are approved and developers need deterministic implementation detail.

Do Not Use When

• Do not use to revisit system architecture silently or to generate code without approved behavioural contracts.

Required Inputs

Workflow

1. Read the named inputs and confirm their approval, version and unresolved decisions.
2. Apply the decision rules below before drafting; stop on a missing authority, unsafe assumption or unresolved scope driver.
3. Produce the Low-Level Design and traceability notes through the existing domain procedure and load only the references needed for the chosen branch.
4. Trace each material statement in the Low-Level Design and traceability notes to an input, decision or explicitly qualified assumption.
5. Verify the observable acceptance conditions, record unassessed checks, and hand the artefacts to their named consumers.
6. If validation fails, recover by correcting the source decision or artefact and rerun the affected check; do not weaken the acceptance condition.

Outputs

Evidence Produced

Capability and permission boundaries

Read-only is the default for analysis, review, evaluation and planning. Read and search access to authorised project artefacts are required. Editing is limited to an explicitly requested project deliverable. Execution may run document, syntax or validation checks. Network access is used only for facts that require current verification. Do not publish, spend, change production, approve policy, or claim certification without explicit authority.

Degraded mode

If any required capability is unavailable, return the narrowest useful qualified Low-Level Design and traceability notes draft plus a gap register showing the missing item, affected sections, risk and owner. Never convert an unassessed check into a pass.

Decision Rules

Quality Standards

• Preserve repository terminology and trace every material choice to project context.
• Use deterministic acceptance conditions; replace vague quality claims with an observable check, threshold or named approval.
• Cover error, empty, edge, recovery and operational cases relevant to this skill.
• Verify standards, citations, APIs and package names before relying on them; qualify what cannot be checked.
• Stop release for a failed safety, security, legal, financial, accessibility or data-integrity gate.

Anti-Patterns

• Repeating HLD component boxes. Fix: specify units, state and call sequence.
• Writing pseudocode with undefined failure paths. Fix: define errors and recovery.
• Inventing framework APIs. Fix: verify the selected stack or stay technology-neutral.
• Ignoring concurrency and idempotency. Fix: state the invariant and race handling.
• Producing classes with no requirement trace. Fix: map each responsibility to an approved requirement.

References

• High-Level Design neighbour
• API Specification neighbour
• Database Design neighbour

Overview

This is the second skill in Phase 03 (Design Documentation). It decomposes the high-level components defined in HLD.md into implementable modules with class structures, interaction sequences, state transitions, and algorithmic detail. The resulting LLD.md serves as the definitive blueprint for developers, mapping every module back to its originating HLD component and SRS requirement.

When to Use

• After the 01-high-level-design skill has produced HLD.md in projects/<ProjectName>/<phase>/<document>/.
• Requires business_rules.md in projects/<ProjectName>/_context/ for algorithm formalization and calculation logic.

Quick Reference

Input Files

Output Files

Core Instructions

Follow these nine steps in order. Halt and notify the user if a required input file is missing.

Step 1: Read and Validate Inputs

Read HLD.md and SRS_Draft.md from projects/<ProjectName>/<phase>/<document>/, and business_rules.md from projects/<ProjectName>/_context/. Log every file path read. If any required file is missing, halt execution and report the gap.

Step 2: Decompose Components into Modules

For each component identified in HLD.md, decompose it into modules and classes. Define each module's single responsibility, public interface, and internal dependencies. Group related classes into packages or namespaces that mirror the HLD layered architecture.

Step 3: Generate Class Diagrams

Produce Mermaid classDiagram blocks for each module. Classes shall include:

• Typed attributes (String, Integer, DECIMAL(19,4) for monetary values, DateTime)
• Parameterized methods with return types
• Relationships: inheritance (<|--), composition (*--), dependency (..>), association (-->)

classDiagram
    class Order {
        -orderId : UUID
        -totalAmount : DECIMAL(19,4)
        +calculateTotal() : DECIMAL(19,4)
        +applyDiscount(rate : DECIMAL(5,4)) : void
    }
    class OrderItem {
        -quantity : Integer
        -unitPrice : DECIMAL(19,4)
    }
    Order *-- OrderItem : contains

Step 4: Generate Sequence Diagrams

Produce Mermaid sequenceDiagram blocks for 5-8 critical workflows derived from SRS Section 3.2 stimulus-response pairs. Each diagram shall show:

• Actor-to-component message flows
• Both the happy path and at least one error/alternate path
• Return values and asynchronous callbacks where applicable

sequenceDiagram
    actor User
    participant Controller
    participant Service
    User->>Controller: submitOrder(orderData)
    Controller->>Service: processOrder(orderData)
    Service-->>Controller: OrderConfirmation
    Controller-->>User: 201 Created

Step 5: Generate State Machine Diagrams

Produce Mermaid stateDiagram-v2 blocks for every entity that has lifecycle states. Each diagram shall include all terminal states and transition guards.

stateDiagram-v2
    [*] --> Created
    Created --> Confirmed : payment_verified
    Confirmed --> Processing : fulfillment_started
    Processing --> Shipped : tracking_assigned
    Shipped --> Delivered : delivery_confirmed
    Delivered --> Completed : dispute_period_elapsed
    Created --> Cancelled : user_cancels
    Confirmed --> Cancelled : admin_cancels

Step 6: Formalize Business Rules as Algorithms

For each complex business rule in business_rules.md, produce structured pseudocode. Use LaTeX notation for all calculations:

• $LateFee = Balance \times Rate \times DaysOverdue$
• $Discount = SubTotal \times DiscountRate$ where $SubTotal > MinThreshold$

Include preconditions, postconditions, and edge-case guards for every algorithm. Document time complexity where relevant.

Step 7: Design Error Handling

Define a comprehensive error handling strategy:

• Error Code Taxonomy: Enumerate domain-specific error codes mapped to HTTP status codes (e.g., ORD-4001: Invalid order state transition -> 409 Conflict).
• Exception Hierarchy: Design the exception class tree (e.g., ApplicationException -> ValidationException, BusinessRuleException, IntegrationException).
• Recovery Behavior: Specify retry policy, fallback, or escalation per error type.

Step 8: Define Data Validation Rules

For each input accepted by a module, define validation constraints per ISO/IEC 25062:

• Data type and format (e.g., email regex, ISO 8601 dates)
• Range checks (min/max values, string length bounds)
• Required vs. optional fields
• Cross-field validation rules (e.g., endDate > startDate)

Step 9: Generate Traceability Matrix and Write Output

Produce a traceability table mapping every LLD module to its HLD component and originating SRS requirement ID:

Write the completed document to projects/<ProjectName>/<phase>/<document>/LLD.md. Log the total module count, diagram count, and algorithm count.

Output Format

The generated LLD.md shall follow this structure:

# Low-Level Design: [Project Name]
## Document Header
## 1. Introduction and Scope
## 2. Module Decomposition
### 2.x [Module Name] -- Responsibility, Class Diagram, Dependencies
## 3. Interaction Sequences
### 3.x [Workflow Name] Sequence Diagram
## 4. State Machine Models
### 4.x [Entity Name] State Diagram
## 5. Algorithm Specifications
### 5.x [Rule Name] Pseudocode
## 6. Error Handling Design (Taxonomy, Hierarchy, Recovery)
## 7. Data Validation Rules
## 8. Traceability Matrix
## Appendix A: Glossary

Common Pitfalls

1. Missing state transitions: Every state must have at least one outbound transition or be explicitly terminal. Orphan states indicate incomplete analysis.
2. Incomplete sequence flows: Omitting error paths produces optimistic designs. Every sequence diagram shall include at least one failure branch.
3. Algorithms without edge cases: Division by zero, null inputs, empty collections, and boundary values shall be guarded in every algorithm.
4. Generic error handling: "Catch all exceptions" is not a design. Each error type shall have a specific code, message, and recovery strategy.

Verification Checklist

• Every HLD component decomposes into at least one LLD module with a class diagram.
• Class diagrams use typed attributes (including DECIMAL(19,4) for monetary values) and parameterized methods.
• At least 5 sequence diagrams cover critical workflows with both happy and error paths.
• State machine diagrams include all terminal states and transition guard conditions.
• Every business rule algorithm includes preconditions, postconditions, and edge-case handling.
• Traceability matrix links every LLD module back to HLD components and SRS requirement IDs.

Integration

Standards

• IEEE 1016-2009 Sec 6: Software Design Descriptions. Governs the structure of design viewpoints including decomposition, dependency, interface, and detail views.
• ISO/IEC 25010: Systems and software quality models. Provides the quality attribute framework referenced in module responsibilities.
• ISO/IEC 25062: Common Industry Format for usability test reports. Governs data validation rule documentation format.

Resources

• logic.prompt -- executable prompt for automated LLD generation.
• README.md -- quick-start guide for this skill.