josiadmin/awesome-copilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add edgec-case matrix

Browse Source
This commit is contained in:
Muhammad Ubaid Raza 2025-07-18 16:28:35 +05:00
parent 133c5e77ed
commit 304c0a5749
1 changed files with 193 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

329
instructions/spec-driven-workflow-v1.instructions.md
View File

@ -1,67 +1,41 @@
--- ---
description: 'Specification-Driven Workflow v1 provides a structured approach to software development, ensuring that requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented and validated.' description: 'Specification-Driven Workflow v2 provides a robust, interactive approach to software development, ensuring requirements are clarified before implementation. It prioritizes safety and transparency through structured artifacts and clear protocols, with a proactive approach to edge case handling.'
applyTo: '**' applyTo: '**'
--- ---
# Spec Driven Workflow v1 # Spec Driven Workflow v2
**Specification-Driven Workflow:** **Specification-Driven Workflow:**
Bridge the gap between requirements and implementation. An interactive process to bridge the gap between requirements and implementation safely and transparently, with proactive edge case anticipation to enhance system reliability.
**Maintain these artifacts at all times:** ## Core Principle: Ambiguity Resolution Protocol
- **`requirements.md`**: User stories and acceptance criteria in structured EARS notation. This is the most important rule. The primary goal is to prevent errors by ensuring complete clarity *before* acting.
- **`design.md`**: Technical architecture, sequence diagrams, implementation considerations.
- **`tasks.md`**: Detailed, trackable implementation plan.
## Universal Documentation Framework **If you encounter any ambiguity, inconsistency, or incomplete information in the request or during your process, you MUST stop and ask for clarification. Do not make assumptions. Do not proceed until the ambiguity is resolved.**
**Documentation Rule:** ## Artifacts for Transparency
Use the detailed templates as the **primary source of truth** for all documentation.
**Summary formats:** **Maintain these artifacts at all times.** They serve to make your reasoning process transparent and auditable. They must be reviewed and approved by the user before implementation begins.
Use only for concise artifacts such as changelogs and pull request descriptions.
### Detailed Documentation Templates - **`requirements.md`**: User stories, acceptance criteria, and edge case matrix in structured EARS notation.
- **`design.md`**: Technical architecture, sequence diagrams, implementation considerations, and edge case mitigations.
- **`tasks.md`**: A detailed, trackable implementation plan, including edge case handling tasks.
- **`decision_records.md`**: A record of all significant decisions, their context, options considered, and rationale.
- **`action_log.md`**: A comprehensive log of all actions taken, their outcomes, logs, test results, console outputs, etc.
- **`diagrams/`**: Directory for all relevant diagrams (e.g., sequence diagrams, data flow diagrams) if needed.
#### Action Documentation Template (All Steps/Executions/Tests) ### Recommended File Structure
```bash ```markdown
### [TYPE] - [ACTION] - [TIMESTAMP] /spec/
**Objective**: [Goal being accomplished] ├── requirements.md
**Context**: [Current state, requirements, and reference to prior steps] ├── design.md
**Decision**: [Approach chosen and rationale, referencing the Decision Record if applicable] ├── tasks.md
**Execution**: [Steps taken with parameters and commands used. For code, include file paths.] ├── decision_records.md
**Output**: [Complete and unabridged results, logs, command outputs, and metrics] ├── action_log.md
**Validation**: [Success verification method and results. If failed, include a remediation plan.] └── diagrams/
**Next**: [Automatic continuation plan to the next specific action]
``` ```
#### Decision Record Template (All Decisions)
```bash
### Decision - [TIMESTAMP]
**Decision**: [What was decided]
**Context**: [Situation requiring decision and data driving it]
**Options**: [Alternatives evaluated with brief pros and cons]
**Rationale**: [Why the selected option is superior, with trade-offs explicitly stated]
**Impact**: [Anticipated consequences for implementation, maintainability, and performance]
**Review**: [Conditions or schedule for reassessing this decision]
```
### Summary Formats (for Reporting)
#### Streamlined Action Log
For generating concise changelogs. Each log entry is derived from a full Action Document.
`[TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]`
#### Compressed Decision Record
For use in pull request summaries or executive summaries.
`Decision: [X] | Rationale: [Y] | Impact: [Z] | Review: [Date]`
## Execution Workflow (6-Phase Loop) ## Execution Workflow (6-Phase Loop)
**Never skip any step. Use consistent terminology. Reduce ambiguity.** **Never skip any step. Use consistent terminology. Reduce ambiguity.**
@ -70,144 +44,151 @@ For use in pull request summaries or executive summaries.
**Objective:** **Objective:**
- Understand the problem. - Understand the problem, analyze the existing system, produce clear, testable requirements, and proactively identify edge cases to anticipate potential failures before design begins.
- Analyze the existing system.
- Produce a clear, testable set of requirements.
- Think about the possible solutions and their implications.
**Checklist:** **Checklist:**
- [ ] Read all provided code, documentation, tests, and logs. - [ ] Read all provided code, documentation, tests, and logs.
- Document file inventory, summaries, and initial analysis results. - Document file inventory, summaries, and initial analysis results.
- [ ] Define requirements in **EARS Notation**: - [ ] Define requirements in **EARS Notation**:
- Transform feature requests into structured, testable requirements. - Transform feature requests into structured, testable requirements.
- Format: `WHEN [a condition or event], THE SYSTEM SHALL [expected behavior]` - Format: `WHEN [a condition or event], THE SYSTEM SHALL [expected behavior]`
- [ ] Identify dependencies and constraints. - [ ] Identify dependencies and constraints.
- Document a dependency graph with risks and mitigation strategies. - Document a dependency graph with risks and mitigation strategies.
- [ ] Map data flows and interactions. - [ ] Map data flows and interactions.
- Document system interaction diagrams and data models. - Document system interaction diagrams and data models.
- [ ] Catalog edge cases and failures. - [ ] **Proactively catalog edge cases and potential failures**:
- Document a comprehensive edge case matrix and potential failure points. - **Edge Case Brainstorming**: Use a structured framework (e.g., input-output analysis, boundary value analysis, or failure mode analysis) to anticipate edge cases.
- **Input Analysis**: Identify extreme, invalid, or unexpected inputs (e.g., null values, oversized data, malformed data).
- **State Analysis**: Consider system states (e.g., offline, maintenance mode, high load) and transitions.
- **User Behavior**: Anticipate unexpected user actions (e.g., rapid clicks, partial form submissions).
- **Environmental Factors**: Account for external factors (e.g., network failures, low memory, time zone issues).
- **Edge Case Prioritization**: Assign a **Risk Score (0-100)** to each edge case based on:
- **Likelihood**: Probability of occurrence (e.g., rare, occasional, frequent).
- **Impact**: Severity of failure (e.g., minor UI glitch, data loss, system crash).
- **Mitigation Complexity**: Effort required to address the edge case.
- Document prioritized edge cases in an **Edge Case Matrix** in `requirements.md`:
- Format: `[Edge Case Description], [Likelihood], [Impact], [Risk Score], [Preliminary Mitigation Strategy]`
- [ ] Assess confidence. - [ ] Assess confidence.
- Generate a **Confidence Score (0-100%)** based on clarity of requirements, complexity, and problem scope. - Generate a **Confidence Score (0-100%)** based on clarity of requirements, complexity, problem scope, and coverage of edge cases.
- Document the score and its rationale. - Document the score and its rationale, including how edge case identification impacts confidence.
**Critical Constraint:** **Critical Constraint:**
- **Do not proceed until all requirements are clear and documented.** - **Do not proceed if requirements or edge cases are ambiguous.** You must halt and request clarification.
- **Do not proceed until all requirements and prioritized edge cases are clear and documented.**
### **Phase 2: DESIGN** ### **Phase 2: DESIGN**
**Objective:** **Objective:**
- Create a comprehensive technical design and a detailed implementation plan. - Create a comprehensive technical design and implementation plan that proactively addresses prioritized edge cases to ensure robustness and reliability.
**Checklist:** **Checklist:**
- [ ] **Define adaptive execution strategy based on Confidence Score:** - [ ] **Define adaptive execution strategy based on Confidence Score:**
- **High Confidence (>85%)** - **High Confidence (>85%)**
- Draft a comprehensive, step-by-step implementation plan. - Draft a comprehensive, step-by-step implementation plan, including edge case mitigations.
- Skip proof-of-concept steps. - Skip proof-of-concept steps unless edge cases introduce significant risk.
- Proceed with full, automated implementation. - Proceed with full, automated implementation.
- Maintain standard comprehensive documentation. - Maintain standard comprehensive documentation.
- **Medium Confidence (66–85%)** - **Medium Confidence (66–85%)**
- Prioritize a **Proof-of-Concept (PoC)** or **Minimum Viable Product (MVP)**. - Prioritize a **Proof-of-Concept (PoC)** or **Minimum Viable Product (MVP)** to validate edge case handling.
- Define clear success criteria for PoC/MVP. - Define clear success criteria for PoC/MVP, including edge case scenarios.
- Build and validate PoC/MVP first, then expand plan incrementally. - Build and validate PoC/MVP first, then expand plan incrementally.
- Document PoC/MVP goals, execution, and validation results. - Document PoC/MVP goals, execution, and validation results.
- **Low Confidence (<66%)** - **Low Confidence (<66%)**
- Dedicate first phase to research and knowledge-building. - Dedicate first phase to research and knowledge-building, including simulation of high-risk edge cases.
- Use semantic search and analyze similar implementations. - Use semantic search and analyze similar implementations for edge case patterns.
- Synthesize findings into a research document. - Synthesize findings into a research document.
- Re-run ANALYZE phase after research. - Re-run ANALYZE phase after research, updating the Edge Case Matrix.
- Escalate only if confidence remains low. - Escalate only if confidence remains low.
- [ ] **Document technical design in `design.md`:** - [ ] **Document technical design in `design.md`:**
- **Architecture:** High-level overview of components and interactions. - **Architecture:** High-level overview of components and interactions, including edge case handling mechanisms.
- **Data Flow:** Diagrams and descriptions. - **Data Flow:** Diagrams and descriptions, highlighting edge case paths.
- **Interfaces:** API contracts, schemas, public-facing function signatures. - **Interfaces:** API contracts, schemas, public-facing function signatures, with validation for edge case inputs.
- **Data Models:** Data structures and database schemas. - **Data Models:** Data structures and database schemas, accounting for edge case data scenarios.
- [ ] **Document error handling and edge case mitigation:**
- [ ] **Document error handling:** - Update the error matrix to include procedures for handling prioritized edge cases from the Edge Case Matrix.
- Create an error matrix with procedures and expected responses. - Specify fallback behaviors, retry mechanisms, or user notifications for each edge case.
- [ ] **Define unit testing strategy for edge cases:**
- [ ] **Define unit testing strategy.** - Create test cases specifically targeting each prioritized edge case in the Edge Case Matrix.
- Include boundary tests, invalid input tests, and stress tests.
- [ ] **Create implementation plan in `tasks.md`:** - [ ] **Create implementation plan in `tasks.md`:**
- For each task, include description, expected outcome, and dependencies. - For each task, include description, expected outcome, dependencies, and specific edge case mitigations.
**Critical Constraint:** **Critical Constraint:**
- **Do not proceed to implementation until design and plan are complete and validated.** - **Do not proceed to implementation until the design, implementation plan, and edge case mitigations are complete and validated.**
### **Phase 3: IMPLEMENT** ### **Phase 3: IMPLEMENT**
**Objective:** **Objective:**
- Write production-quality code according to the design and plan. - Write production-quality code according to the design and plan, incorporating edge case mitigations.
**Checklist:** **Checklist:**
- [ ] Code in small, testable increments. - [ ] Code in small, testable increments.
- Document each increment with code changes, results, and test links. - Document each increment with code changes, results, and test links.
- [ ] Implement from dependencies upward. - [ ] Implement from dependencies upward.
- Document resolution order, justification, and verification. - Document resolution order, justification, and verification.
- [ ] Follow conventions. - [ ] Follow conventions.
- Document adherence and any deviations with a Decision Record. - Document adherence and any deviations with a Decision Record.
- [ ] Add meaningful comments. - [ ] Add meaningful comments.
- Focus on intent ("why"), not mechanics ("what"). - Focus on intent ("why"), not mechanics ("what").
- [ ] Create files as planned. - [ ] Create files as planned.
- Document file creation log. - Document file creation log.
- [ ] Update task status in real time. - [ ] Update task status in real time, including edge case mitigation implementation.
**Critical Constraint:** **Critical Constraint:**
- **Do not merge or deploy code until all implementation steps are documented and tested.** - **Do not merge or deploy code until all implementation steps, including edge case mitigations, are documented and tested.**
### **Phase 4: VALIDATE** ### **Phase 4: VALIDATE**
**Objective:** **Objective:**
- Verify that implementation meets all requirements and quality standards. - Verify that implementation meets all requirements, quality standards, and edge case mitigations.
**Checklist:** **Checklist:**
- [ ] Execute automated tests. - [ ] Execute automated tests.
- Document outputs, logs, and coverage reports. - Document outputs, logs, and coverage reports, including edge case test results.
- For failures, document root cause analysis and remediation. - For failures, document root cause analysis and remediation.
- [ ] Perform manual verification if necessary. - [ ] Perform manual verification if necessary.
- Document procedures, checklists, and results. - Document procedures, checklists, and results.
- [ ] Test edge cases and errors. - [ ] Test edge cases and errors.
- Document results and evidence of correct error handling. - Document results and evidence of correct edge case handling.
- [ ] Verify performance. - [ ] Verify performance.
- Document metrics and profile critical sections. - Document metrics and profile critical sections.
- [ ] Log execution traces. - [ ] Log execution traces.
- Document path analysis and runtime behavior. - Document path analysis and runtime behavior.
**Critical Constraint:** **Critical Constraint:**
- **Do not proceed until all validation steps are complete and all issues are resolved.** - **Do not proceed until all validation steps are complete and all issues, including edge case-related issues, are resolved.**
### **Phase 5: REFLECT** ### **Phase 5: REFLECT**
**Objective:** **Objective:**
- Improve codebase, update documentation, and analyze performance. - Improve codebase, update documentation, analyze performance, and evaluate edge case mitigation effectiveness.
**Checklist:** **Checklist:**
- [ ] Refactor for maintainability. - [ ] Refactor for maintainability.
- Document decisions, before/after comparisons, and impact. - Document decisions, before/after comparisons, and impact.
- [ ] Update all project documentation. - [ ] Update all project documentation.
- Ensure all READMEs, diagrams, and comments are current. - Ensure all READMEs, diagrams, and comments are current, including edge case documentation.
- [ ] Identify potential improvements. - [ ] Identify potential improvements.
- Document backlog with prioritization. - Document backlog with prioritization, including missed edge cases or over-engineered mitigations.
- [ ] Validate success criteria. - [ ] Validate success criteria.
- Document final verification matrix. - Document final verification matrix, including edge case outcomes.
- [ ] Perform meta-analysis. - [ ] Perform meta-analysis.
- Reflect on efficiency, tool usage, and protocol adherence. - Reflect on efficiency, tool usage, protocol adherence, and edge case handling effectiveness.
- [ ] Auto-create technical debt issues. - [ ] Auto-create technical debt issues.
- Document inventory and remediation plans. - Document inventory and remediation plans, including missed edge cases.
**Critical Constraint:** **Critical Constraint:**
@ -217,21 +198,21 @@ For use in pull request summaries or executive summaries.
**Objective:** **Objective:**
- Package work for review and deployment, and transition to next task. - Package work for review and deployment, including edge case outcomes, and transition to next task.
**Checklist:** **Checklist:**
- [ ] Generate executive summary. - [ ] Generate executive summary.
- Use **Compressed Decision Record** format. - Use **Compressed Decision Record** format, including edge case mitigation outcomes.
- [ ] Prepare pull request (if applicable): - [ ] Prepare pull request (if applicable):
1. Executive summary. 1. Executive summary.
2. Changelog from **Streamlined Action Log**. 2. Changelog from **Streamlined Action Log**.
3. Links to validation artifacts and Decision Records. 3. Links to validation artifacts, Decision Records, and edge case test results.
4. Links to final `requirements.md`, `design.md`, and `tasks.md`. 4. Links to final `requirements.md`, `design.md`, and `tasks.md`.
- [ ] Finalize workspace. - [ ] Finalize workspace.
- Archive intermediate files, logs, and temporary artifacts to `.agent_work/`. - Archive intermediate files, logs, and temporary artifacts to `.agent_work/`.
- [ ] Continue to next task. - [ ] Continue to next task.
- Document transition or completion. - Document transition or completion.
**Critical Constraint:** **Critical Constraint:**
@ -244,17 +225,16 @@ For use in pull request summaries or executive summaries.
**Checklist:** **Checklist:**
1. **Re-analyze**: 1. **Re-analyze**:
- Revisit the ANALYZE phase. - Revisit the ANALYZE phase, focusing on missed edge cases or ambiguities in the Edge Case Matrix.
- Confirm all requirements and constraints are clear and complete. - Confirm all requirements, constraints, and edge cases are clear and complete.
2. **Re-design**: 2. **Re-design**:
- Revisit the DESIGN phase. - Update the technical design and Edge Case Matrix to address newly identified edge cases or failures.
- Update technical design, plans, or dependencies as needed.
3. **Re-plan**: 3. **Re-plan**:
- Adjust the implementation plan in `tasks.md` to address new findings. - Adjust the implementation plan in `tasks.md` to include tasks for new edge case mitigations.
4. **Retry execution**: 4. **Retry execution**:
- Re-execute failed steps with corrected parameters or logic. - Re-execute failed steps with updated edge case handling logic.
5. **Escalate**: 5. **Escalate**:
- If the issue persists after retries, follow the escalation protocol. - If edge case issues persist after retries, follow the escalation protocol, documenting findings in `decision_records.md`.
**Critical Constraint:** **Critical Constraint:**
@ -268,6 +248,8 @@ For use in pull request summaries or executive summaries.
- **Shortcuts**: Explicitly record all speed-over-quality decisions with their consequences in a Decision Record. - **Shortcuts**: Explicitly record all speed-over-quality decisions with their consequences in a Decision Record.
- **Workspace**: Monitor for organizational drift and naming inconsistencies. - **Workspace**: Monitor for organizational drift and naming inconsistencies.
- **Documentation**: Track incomplete, outdated, or missing documentation. - **Documentation**: Track incomplete, outdated, or missing documentation.
- **Missed Edge Cases**: Identify and document any edge cases missed during the ANALYZE phase.
- **Over-Engineered Mitigations**: Record edge case mitigations that are overly complex or inefficient.
### Auto-Issue Creation Template ### Auto-Issue Creation Template
@ -294,6 +276,8 @@ For use in pull request summaries or executive summaries.
- **Static Analysis**: Linting for code style, quality, security vulnerabilities, and architectural rule adherence. - **Static Analysis**: Linting for code style, quality, security vulnerabilities, and architectural rule adherence.
- **Dynamic Analysis**: Monitor runtime behavior and performance in a staging environment. - **Dynamic Analysis**: Monitor runtime behavior and performance in a staging environment.
- **Documentation**: Automated checks for documentation completeness and accuracy (e.g., linking, format). - **Documentation**: Automated checks for documentation completeness and accuracy (e.g., linking, format).
- **Edge Case Coverage**: Track the percentage of edge cases in the Edge Case Matrix with corresponding tests and mitigations.
- **Edge Case Risk Reduction**: Measure the reduction in Risk Scores post-mitigation via validation results.
### Quality Metrics (Auto-Tracked) ### Quality Metrics (Auto-Tracked)
@ -302,22 +286,95 @@ For use in pull request summaries or executive summaries.
- Maintainability index assessment. - Maintainability index assessment.
- Technical debt ratio (e.g., estimated remediation time vs. development time). - Technical debt ratio (e.g., estimated remediation time vs. development time).
- Documentation coverage percentage (e.g., public methods with comments). - Documentation coverage percentage (e.g., public methods with comments).
- Edge case coverage percentage (e.g., edge cases with implemented mitigations).
## EARS Notation Reference ## Concrete "Few-Shot" Examples
**EARS (Easy Approach to Requirements Syntax)** - Standard format for requirements: Use these examples to guide the format and quality of your generated artifacts.
- **Ubiquitous**: `THE SYSTEM SHALL [expected behavior]` ### Example: EARS Requirement (`requirements.md`)
- **Event-driven**: `WHEN [trigger event] THE SYSTEM SHALL [expected behavior]`
- **State-driven**: `WHILE [in specific state] THE SYSTEM SHALL [expected behavior]`
- **Unwanted behavior**: `IF [unwanted condition] THEN THE SYSTEM SHALL [required response]`
- **Optional**: `WHERE [feature is included] THE SYSTEM SHALL [expected behavior]`
- **Complex**: Combinations of the above patterns for sophisticated requirements
Each requirement must be: ```markdown
### Requirements
- **Event-driven**: `WHEN the user clicks the "Export PDF" button, THE SYSTEM SHALL generate a PDF of the current report.`
- **Unwanted behavior**: `IF the user attempts to run an export while another export is in progress, THEN THE SYSTEM SHALL display the error message "An export is already in progress. Please wait."`
- **State-driven**: `WHILE the system is in "maintenance mode", THE SYSTEM SHALL disable the "Run Analysis" button.`
- **Testable**: Can be verified through automated or manual testing ### Edge Case Matrix
- **Unambiguous**: Single interpretation possible | Edge Case Description | Likelihood | Impact | Risk Score | Preliminary Mitigation Strategy |
- **Necessary**: Contributes to the system's purpose | -------------------------------------------------------- | ---------- | ------ | ---------- | ---------------------------------------------------------------------- |
- **Feasible**: Can be implemented within constraints | Report data is null or empty | Occasional | High | 75 | Validate input data before processing; throw `InvalidReportDataError`. |
- **Traceable**: Linked to user needs and design elements | User initiates multiple exports simultaneously | Frequent | Medium | 70 | Lock export button during processing; queue subsequent requests. |
| System runs out of memory during large report generation | Rare | High | 80 | Stream data processing to minimize memory usage. |
```
### Example: Design Document Snippet (`design.md`)
```markdown
**Component**: `ReportGeneratorService`
**Function**: `generatePdf(reportData)`
**Logic**:
1. Validate `reportData` for null or empty values.
2. Uses the `PDF-lib` library to construct the document.
3. Serializes charts using `Chart.js` canvas export.
4. Fetches header and footer templates.
5. Assembles the final PDF and returns it as a byte stream.
**Edge Case Handling**:
- **Null or Empty Report Data (Risk Score: 75)**:
- **Mitigation**: Check for null/empty data; throw `InvalidReportDataError` with message "Report data cannot be empty."
- **Test Plan**: Unit tests with null and empty inputs to verify error handling.
- **Multiple Simultaneous Exports (Risk Score: 70)**:
- **Mitigation**: Implement a locking mechanism to disable the export button during processing.
- **Test Plan**: Simulate concurrent export requests to verify queuing behavior.
**Error Handling**: Throws `InvalidReportDataError` for invalid inputs; logs concurrent export attempts.
```
### Example: Task Entry (`tasks.md`)
```markdown
- **Task**: Implement `generatePdf` function in `ReportGeneratorService`.
- **ID**: task-001
- **Depends on**: `ReportData` model definition.
- **Status**: To Do
- **Outcome**: A function that correctly generates a PDF byte stream from a valid data object.
- **Edge Case Mitigation**: Validates input data to handle null/empty edge case.
- **Task**: Implement client-side form validation for `FormSubmissionService`.
- **ID**: task-002
- **Depends on**: `FormSubmissionService` component definition.
- **Status**: To Do
- **Outcome**: Submit button is disabled until all required fields are filled, addressing empty form edge case.
- **Edge Case Mitigation**: Validates inputs in real-time using JavaScript event listeners.
```
### Example: Decision Record (`decision_records.md`)
```markdown
### Decision - 2025-07-18T15:20:00Z
**Decision**: Use `PDF-lib` over `jsPDF` for PDF generation.
**Context**: The project requires client-side PDF generation with support for modifying existing PDFs in the future.
**Options**:
1. **`PDF-lib`**: Pro: Modern API, good support for document manipulation. Con: Slightly smaller community.
2. **`jsPDF`**: Pro: Mature, large community, extensive plugins. Con: API is older and can be less intuitive for complex modifications.
**Rationale**: `PDF-lib`'s focus on document manipulation aligns better with the long-term project roadmap, which includes features for merging and annotating PDFs. The modern API is also expected to reduce development time.
**Impact**: Implementation will rely on a slightly less common library, requiring careful dependency management.
**Review**: Re-evaluate this choice in 12 months or if significant performance issues arise.
```
### Example: Action Log Record (`action_log.md`)
```markdown
- **Action**: Implemented `generatePdf` function.
- **Outcome**: Function successfully generates a PDF from provided report data.
- **Logs**: [Link to console output]
- **Tests**: [Link to unit tests]
- **Issues**: No issues encountered.
- **Edge Case Outcome**: Successfully handled null/empty input with `InvalidReportDataError`.
- **Next Steps**: Validate PDF generation with various report data inputs, including edge cases.
```