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 of structured documentation and progress tracking within GitHub issues. By providing standardized templates for implementation plans, status updates, and completion summaries, it enhances team transparency, ensures technical alignment, and maintains a clear audit trail of the development lifecycle.
Use Cases
- Initiating development tasks by posting a structured 'Implementation Started' comment that defines objectives, technical approaches, and success criteria.
- Providing periodic progress updates to stakeholders by documenting completed items, current work-in-progress, and any blockers directly within the issue thread.
- Finalizing work with a comprehensive 'Completion Summary' that links to relevant Pull Requests, lists modified files, and documents verification results for QA purposes.
- Standardizing documentation across a development team to ensure all issues follow the same reporting format and quality standards.
| 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 |
| user-invocable | false |
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