commit 3967cc87375d2d6921f23fcf002f4eae0fdcc00f Author: Zhongwei Li Date: Sun Nov 30 08:52:46 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..5b3300e --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "reporting-skills", + "description": "Collection of reporting requirements skills", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Robin Collins", + "email": "robin.f.collins@outlook.com" + }, + "skills": [ + "./skills/changelog", + "./skills/report-writing" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..a88abac --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# reporting-skills + +Collection of reporting requirements skills diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..202a48a --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,60 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:robin-collins/claude_code_skills:reporting-skills", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "884de7fcdeeb3187ddf0ab1e2bec9fab1e79c8c9", + "treeHash": "b63f1b99da12ef66b616cae5359dd0aef71d1c2db1384f14477ee33873eb5044", + "generatedAt": "2025-11-28T10:28:02.147747Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "reporting-skills", + "description": "Collection of reporting requirements skills" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "e04070dc935eb90b93403496c396c44e1ff6009115836dcce78168387ab2c822" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "a0af5cd663bb0648305ee13146e06dbb9299ba0df1d42d6762333e28a1c4303c" + }, + { + "path": "skills/report-writing/SKILL.md", + "sha256": "7e4b601d7c13e85e432600de6fe2ca405544570e5cf0c4b92398ccb5273a758f" + }, + { + "path": "skills/report-writing/LICENSE.txt", + "sha256": "58d1e17ffe5109a7ae296caafcadfdbe6a7d176f0bc4ab01e12a689b0499d8bd" + }, + { + "path": "skills/report-writing/references/report-template.md", + "sha256": "f0355111f9a356c19fed55eb420bc08776f89b9900da8d4041053b1c5eaa2b54" + }, + { + "path": "skills/changelog/SKILL.md", + "sha256": "e1705f546ac14e361715eee77b1754ee81001013527c028e21def059755004ac" + }, + { + "path": "skills/changelog/LICENSE.txt", + "sha256": "58d1e17ffe5109a7ae296caafcadfdbe6a7d176f0bc4ab01e12a689b0499d8bd" + } + ], + "dirSha256": "b63f1b99da12ef66b616cae5359dd0aef71d1c2db1384f14477ee33873eb5044" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/changelog/LICENSE.txt b/skills/changelog/LICENSE.txt new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/skills/changelog/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/skills/changelog/SKILL.md b/skills/changelog/SKILL.md new file mode 100644 index 0000000..25a4371 --- /dev/null +++ b/skills/changelog/SKILL.md @@ -0,0 +1,234 @@ +--- +name: changelog-management +description: Maintain project documentation including CHANGELOG.md, FILETREE.md, and FAILURELOG.md. Use this skill when making code changes, adding features, fixing bugs, restructuring files/directories, or when initial solutions fail. This skill ensures consistent documentation of all changes using Keep a Changelog format with semantic versioning. +--- + +# Changelog and Documentation Management + +## Purpose + +This skill provides systematic guidance for maintaining three mandatory project documentation files: CHANGELOG.md, FILETREE.md, and FAILURELOG.md. It ensures consistent tracking of all code changes, structural modifications, and debugging attempts using industry-standard formats. + +## When to Use This Skill + +Trigger this skill when: + +- Making any code changes, feature additions, or bug fixes +- Adding, removing, or restructuring files or directories +- Initial solutions fail and debugging is required +- Completing any development task that affects the project state + +## Documentation Requirements + +### CHANGELOG.md - Change Tracking + +**Update CHANGELOG.md for every code modification.** + +Follow [Keep a Changelog](https://keepachangelog.com/) format with semantic versioning: + +- Use standard categories: Added, Changed, Deprecated, Removed, Fixed, Security +- Include date stamps (YYYY-MM-DD) and version numbers for releases +- Reference GitHub issues/PRs when applicable +- Write clear, concise descriptions of changes +- Group related changes under appropriate category headings + +### FILETREE.md - Structure Documentation + +**Update FILETREE.md for any structural changes.** + +Maintain accurate project structure representation: + +- Add entries when creating new files or directories +- Remove entries when deleting files or directories +- Update paths when restructuring +- Include brief descriptions for new directories or significant files +- Keep the tree structure accurate and readable + +### FAILURELOG.md - Debugging History + +**Document all failed attempts when initial solutions don't work.** + +Include comprehensive debugging information: + +- What was tried (approach, code, commands) +- Error messages encountered (full stack traces when relevant) +- Root cause analysis (why it failed) +- Resolution approach (what finally worked) +- Lessons learned to prevent repeating the same debugging cycles + +This is essential for complex integration issues and helps maintain institutional knowledge. + +## Changelog Entry Format + +Use this structure for all CHANGELOG.md entries: + +```markdown +## [Version] - YYYY-MM-DD + +### Added + +- New features or functionality +- New files, endpoints, or capabilities +- New dependencies or tools + +### Changed + +- Modifications to existing features +- Refactoring or improvements +- Updated dependencies or configurations + +### Deprecated + +- Features marked for future removal +- Old APIs or endpoints being phased out + +### Removed + +- Deleted features, files, or functionality +- Removed dependencies + +### Fixed + +- Bug fixes and error corrections +- Performance issue resolutions +- Corrected behavior + +### Security + +- Security patches and improvements +- Vulnerability fixes +- New security features or validations +``` + +### Example Entry + +```markdown +## [1.2.0] - 2025-11-15 + +### Added + +- Customer search endpoint with fuzzy matching (#123) +- Export functionality for animal records to CSV format +- Automated backup system with daily scheduling + +### Changed + +- Updated Prisma client to v5.7.0 for performance improvements +- Refactored authentication middleware for better error handling + +### Fixed + +- Resolved memory leak in file upload handler (#145) +- Fixed date formatting issues in customer reports +- Corrected phone number validation regex + +### Security + +- Added rate limiting to prevent API abuse +- Implemented input sanitization for search queries +``` + +## Version Management + +Apply semantic versioning (MAJOR.MINOR.PATCH) consistently: + +- **MAJOR**: Breaking API changes, incompatible updates +- **MINOR**: New features that are backward compatible +- **PATCH**: Bug fixes that are backward compatible +- Tag releases in git with version numbers (e.g., `v1.2.0`) + +### Version Increment Guidelines + +Increment version numbers based on change significance: + +- Breaking changes → increment MAJOR (1.2.3 → 2.0.0) +- New features → increment MINOR (1.2.3 → 1.3.0) +- Bug fixes → increment PATCH (1.2.3 → 1.2.4) + +## Project-Specific Considerations + +### API Changes + +When modifying APIs: + +- Document all endpoint modifications in Changed or Added +- Include request/response schema changes +- Note deprecation timelines for removed features +- Provide migration examples for breaking changes + +### Database Schema Updates + +When updating database schemas: + +- Document migration scripts and procedures +- Note data transformation requirements +- Include rollback procedures for critical changes +- Specify Prisma version compatibility + +### Performance Improvements + +When optimizing performance: + +- Document changes with before/after metrics when available +- Include configuration changes that affect performance +- Note any new hardware or dependency requirements +- Quantify improvements (e.g., "Reduced load time by 40%") + +### Security Updates + +When addressing security: + +- Use the Security category in CHANGELOG.md +- Reference CVE numbers if applicable +- Describe the vulnerability and fix without exposing exploits +- Include upgrade instructions if dependencies are updated + +## Workflow Integration + +### Standard Development Workflow + +1. Make code changes or add features +2. Update CHANGELOG.md with appropriate category entries +3. Update FILETREE.md if files/directories were added or removed +4. Commit changes with descriptive commit message +5. Reference the changelog entry in PR description + +### Debugging Workflow + +1. Attempt solution and encounter failure +2. Document attempt in FAILURELOG.md immediately: + - Timestamp the entry + - Describe what was tried + - Include error messages + - Note hypothesis about cause +3. Try alternative solution +4. Update FAILURELOG.md with resolution +5. Update CHANGELOG.md with the fix + +### Release Workflow + +1. Review all [Unreleased] entries in CHANGELOG.md +2. Determine appropriate version number using semantic versioning +3. Replace [Unreleased] with [Version] - YYYY-MM-DD +4. Create git tag with version number +5. Update any version references in package.json or similar files + +## Best Practices + +- **Be specific**: Avoid vague descriptions like "Fixed bugs" or "Updated code" +- **Group related changes**: Combine related modifications under a single bullet point +- **Use present tense**: Write "Add feature" not "Added feature" +- **Include context**: Mention the affected component or file when helpful +- **Link issues**: Reference GitHub issues/PRs for traceability +- **Update immediately**: Don't batch documentation updates; maintain them with code changes +- **Review before commit**: Ensure documentation accurately reflects all changes made + +## Common Pitfalls to Avoid + +- Forgetting to update CHANGELOG.md for "small" changes +- Using inconsistent category names (stick to the six standard categories) +- Placing entries in wrong categories (e.g., bug fix in Added instead of Fixed) +- Missing FILETREE.md updates when adding new directories +- Skipping FAILURELOG.md documentation during difficult debugging sessions +- Using incorrect date format (must be YYYY-MM-DD) +- Incrementing version numbers incorrectly diff --git a/skills/report-writing/LICENSE.txt b/skills/report-writing/LICENSE.txt new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/skills/report-writing/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/skills/report-writing/SKILL.md b/skills/report-writing/SKILL.md new file mode 100644 index 0000000..c4c949b --- /dev/null +++ b/skills/report-writing/SKILL.md @@ -0,0 +1,146 @@ +--- +name: report-writing +description: Generate structured task completion reports in two synchronized formats - a concise chat summary and a detailed documentation file. Use this skill when completing tasks that require formal documentation, audit trails, or reproducible records of work performed. Particularly useful for specification-driven development, API implementation, or any workflow requiring both user-facing summaries and comprehensive technical documentation. +--- + +# Report Writing Skill + +This skill provides a standardized protocol for generating task completion reports that serve dual purposes: immediate user communication and long-term documentation. + +## When to Use This Skill + +Invoke this skill upon successful completion of any tasks + +## Core Workflow + +### Two Synchronized Outputs + +Generate both outputs synchronously upon task completion: + +#### 1. Chat Interface Report + +Deliver a concise, user-friendly summary directly to the chat interface: + +- **Format**: Brief, accessible language +- **Content**: Task status, key outcomes, next steps (if applicable) +- **Timing**: Immediate upon completion +- **Audience**: End user or stakeholder + +#### 2. Detailed Documentation File + +Create a comprehensive Markdown file with full implementation details: + +- **Location**: `reports/{specifications_document_name}/task_{task_number}_completed.md` +- **Naming Example**: `reports/ast-transcription-api/task_10_1_completed.md` +- **Structure**: See template in `references/report-template.md` + +### Required Sections in Documentation File + +Structure the detailed documentation file with these sections in order: + +1. **Chat Interface Output** + - Reproduce the complete chat summary verbatim at the top + - Ensures consistency between both deliverables + - Provides context for readers reviewing only the file + +2. **Task Overview** + - Brief description of the task + - Stated objectives and success criteria + - Reference to parent specification or project context + +3. **Execution Timeline** + - Chronological sequence of actions taken + - Timestamp each major step + - Include decision points and reasoning + +4. **Inputs/Outputs** + - All data processed (files read, APIs called, databases queried) + - All artifacts generated (files created, API responses, database modifications) + - Configuration changes or environment setup + +5. **Error Handling** + - Any warnings encountered during execution + - Errors that occurred and how they were resolved + - Validation failures and remediation steps + - Edge cases discovered + +6. **Final Status** + - Success confirmation with criteria met + - Summary of all deliverables produced + - Known limitations or follow-up items + - Links to related documentation or resources + +## Quality Assurance Checklist + +Before finalizing reports, verify: + +- **Consistency**: Chat summary and file documentation align perfectly +- **Accuracy**: All timestamps are correct and chronologically ordered +- **Completeness**: All required sections are present with substantive content +- **Reproducibility**: Sufficient detail exists to recreate the task execution +- **Clarity**: Technical terms are defined, acronyms explained on first use +- **Traceability**: Links to specifications, commits, or related tasks are included + +## Implementation Guidelines + +### File Organization + +Create the `reports/` directory structure as needed: + +``` +reports/ +├── {specification-name-1}/ +│ ├── task_1_completed.md +│ ├── task_2_completed.md +│ └── task_3_completed.md +└── {specification-name-2}/ + └── task_1_completed.md +``` + +### Naming Conventions + +Follow these patterns strictly: + +- **Directory**: Lowercase, hyphen-separated (e.g., `ast-transcription-api`) +- **File**: `task_{number}_completed.md` or `task_{number}_{subnumber}_completed.md` +- **Examples**: `task_1_completed.md`, `task_10_1_completed.md` + +### Writing Style + +- Use active voice in timeline descriptions +- Be specific about tools, commands, and file paths +- Include exact error messages in error handling section +- Use code blocks for commands, file contents, or outputs +- Add headings to improve scanability + +## Example Usage Scenarios + +### Scenario 1: API Implementation + +After implementing a REST API endpoint: + +1. **Chat**: "Successfully implemented the /api/users endpoint with GET and POST methods. Returns user list with pagination, creates new users with validation. All tests passing." + +2. **File**: `reports/user-management-api/task_3_completed.md` containing: + - The above chat output + - Task overview (implement user CRUD endpoints) + - Timeline (created route files, added validation, wrote tests, deployed) + - Inputs/outputs (schema files, test data, API responses) + - Error handling (validation edge cases, database connection retry logic) + - Final status (endpoints live, 100% test coverage, documentation updated) + +### Scenario 2: Database Migration + +After completing a database schema update: + +1. **Chat**: "Database migration completed successfully. Added 'preferences' table with foreign key to users. Backfilled data for 1,247 existing users. No downtime required." + +2. **File**: `reports/user-preferences-feature/task_2_1_completed.md` containing: + - The above chat output + - Full migration details, SQL scripts used, rollback plan tested + - Verification queries run and their results + - Performance impact analysis + +## References + +For detailed template structure with placeholders, see `references/report-template.md`. diff --git a/skills/report-writing/references/report-template.md b/skills/report-writing/references/report-template.md new file mode 100644 index 0000000..aa83405 --- /dev/null +++ b/skills/report-writing/references/report-template.md @@ -0,0 +1,230 @@ +# Task {NUMBER} Completion Report + +**Project**: {Specification Name} +**Date**: {YYYY-MM-DD} +**Status**: ✅ Complete + +--- + +## Chat Interface Output + +> {PASTE THE COMPLETE CHAT SUMMARY HERE VERBATIM} +> +> This section should contain exactly what was delivered to the user via chat interface, +> ensuring consistency between both deliverables. + +--- + +## Task Overview + +**Task ID**: Task {number} or Task {number}.{subnumber} + +**Description**: {Brief 1-2 sentence description of what this task accomplishes} + +**Objectives**: + +- {Objective 1} +- {Objective 2} +- {Objective 3} + +**Success Criteria**: + +- {Criterion 1: e.g., "All tests passing"} +- {Criterion 2: e.g., "API returns expected JSON structure"} +- {Criterion 3: e.g., "Performance under 200ms response time"} + +**Context**: {Reference to parent specification, related tasks, or project documentation} + +--- + +## Execution Timeline + +### {HH:MM} - Step 1: {Action Description} + +{Detailed description of what was done in this step} + +**Actions**: + +- {Specific action 1} +- {Specific action 2} + +**Decisions**: + +- {Decision made and reasoning} + +**Output**: {What was produced in this step} + +### {HH:MM} - Step 2: {Action Description} + +{Continue chronologically through all major steps...} + +### {HH:MM} - Step N: {Final Action} + +{Last step in the execution} + +--- + +## Inputs/Outputs + +### Inputs + +**Files Read**: + +- `{path/to/file1.ext}` - {Description of what was read and why} +- `{path/to/file2.ext}` - {Description} + +**APIs Called**: + +- `{HTTP_METHOD} {/api/endpoint}` - {Purpose} +- Response: {Brief description of response} + +**Database Queries**: + +```sql +{Example query run} +``` + +- Purpose: {Why this query was needed} +- Results: {Number of rows returned, relevant data} + +**Configuration/Environment**: + +- {Environment variable or config setting}: {Value} +- {Tool version}: {Version number} + +### Outputs + +**Files Created/Modified**: + +- `{path/to/created-file.ext}` - {Description of file contents and purpose} +- `{path/to/modified-file.ext}` - {What was changed} + +**Artifacts Generated**: + +- {Build artifacts, compiled files, generated docs, etc.} + +**API Responses**: + +```json +{ + "example": "response", + "data": "..." +} +``` + +**Database Modifications**: + +- Tables created: {List} +- Rows inserted: {Count and description} +- Schema changes: {Description} + +--- + +## Error Handling + +### Warning 1: {Warning Description} + +**Occurred at**: {Timestamp or step} + +**Message**: + +``` +{Exact warning message} +``` + +**Context**: {What was happening when warning occurred} + +**Resolution**: {How it was addressed or why it was safe to ignore} + +--- + +### Error 1: {Error Description} + +**Occurred at**: {Timestamp or step} + +**Error Message**: + +``` +{Exact error message and stack trace if relevant} +``` + +**Root Cause**: {Analysis of what caused the error} + +**Resolution Steps**: + +1. {First step taken to resolve} +2. {Second step} +3. {Final resolution} + +**Prevention**: {How to avoid this error in the future} + +--- + +### Edge Cases Discovered + +**Edge Case 1**: {Description} + +- **Impact**: {How this affects the implementation} +- **Handling**: {How the code now handles this case} + +**Edge Case 2**: {Description} + +- **Impact**: {Impact description} +- **Handling**: {Handling description} + +--- + +## Final Status + +### Success Confirmation + +✅ **All objectives met**: + +- ✅ {Objective 1} - {Confirmation details} +- ✅ {Objective 2} - {Confirmation details} +- ✅ {Objective 3} - {Confirmation details} + +### Deliverables Summary + +**Code Files**: + +- `{path/to/file.ext}` - {Purpose and contents} + +**Documentation**: + +- `{path/to/doc.md}` - {What was documented} + +**Tests**: + +- `{path/to/test.spec.ts}` - {Test coverage details} +- Test results: {X/Y passing, coverage percentage} + +**Database**: + +- Migrations applied: {List migration files} +- Data integrity verified: {Confirmation} + +### Known Limitations + +- {Limitation 1 and why it exists} +- {Limitation 2 and potential future enhancement} + +### Follow-Up Items + +- [ ] {Optional future enhancement} +- [ ] {Related task to complete next} +- [ ] {Technical debt item to address later} + +### Related Resources + +- Specification: `{link or path to spec document}` +- Related tasks: {Links to task_X_completed.md files} +- Git commit: `{commit hash}` - {commit message} +- Pull request: `{PR number and link if applicable}` +- Documentation: `{links to updated docs}` + +--- + +**Report Generated**: {YYYY-MM-DD HH:MM:SS} +**Author**: Claude Code +**Review Status**: {Pending/Reviewed/Approved}