doc-issue-readme
Post structured documentation to GitHub issue as a comment. Use when starting work on an issue to document approach and track progress.
When & Why to Use This Skill
This Claude skill automates the creation and posting of structured documentation directly to GitHub issues. By providing standardized templates for project objectives, implementation strategies, and real-time progress tracking, it ensures clear communication and maintains a high-quality audit trail for software development lifecycles.
Use Cases
- Task Initialization: Automatically post an 'Implementation Started' comment to a GitHub issue, outlining the specific objectives, technical approach, and files targeted for modification.
- Progress Reporting: Generate standardized updates that communicate completed milestones, current work-in-progress percentages, and any blockers to keep stakeholders informed without manual formatting.
- Final Handover: Create comprehensive 'Implementation Complete' summaries that link to Pull Requests, list all changed files, and document testing verification results to streamline the code review and closing process.
| name | doc-issue-readme |
|---|---|
| description | Post structured documentation to GitHub issue as a comment. Use when starting work on an issue to document approach and track progress. |
| category | doc |
Issue Documentation Skill
Post structured documentation to GitHub issues following ML Odyssey standards.
When to Use
- Starting work on a GitHub issue
- Documenting implementation approach
- Tracking implementation progress
- Consolidating findings and decisions
Quick Reference
# Post documentation to issue
gh issue comment <number> --body "$(cat <<'EOF'
## Issue Documentation
### Objective
[What this issue accomplishes]
### Approach
[Implementation approach]
### Files to Modify
- path/to/file1
- path/to/file2
### Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
EOF
)"
Documentation Format
Starting Work
gh issue comment <number> --body "$(cat <<'EOF'
## Implementation Started
**Branch**: `<branch-name>`
### Objective
[1-2 sentence description of what this issue accomplishes]
### Approach
[Brief description of implementation approach]
### Files to Create/Modify
- [ ] `path/to/file1.mojo` - [purpose]
- [ ] `path/to/file2.mojo` - [purpose]
### Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
### References
- Related: #[other-issue]
- Design: [link to relevant docs]
EOF
)"
Progress Update
gh issue comment <number> --body "$(cat <<'EOF'
## Progress Update
### Completed
- [x] Item 1
- [x] Item 2
### In Progress
- [ ] Item 3 (70%)
### Blockers
None / [describe blockers]
### Notes
[Any findings or decisions made]
EOF
)"
Completion Summary
gh issue comment <number> --body "$(cat <<'EOF'
## Implementation Complete
**PR**: #<pr-number>
### Summary
[What was implemented]
### Files Changed
- `path/to/file1.mojo` - [change description]
- `path/to/file2.mojo` - [change description]
### Testing
- All tests pass
- Coverage: X%
### Verification
- [x] `pixi run test` passes
- [x] `just pre-commit-all` passes
EOF
)"
Workflow
- Read issue context:
gh issue view <number> --comments - Post documentation: Use templates above to document approach
- Update as work progresses: Post progress updates
- Summarize on completion: Post completion summary with PR link
Documentation Rules
DO
- Keep issue-specific
- Reference related issues and docs
- Update as work progresses
- Be specific and measurable
DON'T
- Post overly long updates (split if needed)
- Duplicate content across issues
- Leave work undocumented
- Forget completion summary
Common Sections
Objective
Good: "Implement tensor operations (add, multiply, matmul) with SIMD optimization" Bad: "Work on tensors"
Approach
Good: "Use SIMD for vectorized operations, implement lazy evaluation for chain operations" Bad: "Code stuff"
Success Criteria
Must be measurable checkboxes:
- "All 15 unit tests pass"
- "Coverage > 90%"
- "No new warnings"
Error Handling
| Issue | Fix |
|---|---|
| Issue locked | Contact maintainer |
| Rate limited | Wait and retry |
| Content too long | Split into multiple comments |
| Missing context | Run gh issue view <number> --comments first |
References
- See
.claude/shared/github-issue-workflow.mdfor workflow patterns - See
gh-read-issue-contextskill for reading issue context - See
gh-post-issue-updateskill for posting updates