| name | add-github-permalinks |
| description | Add GitHub permalinks with fixed SHA/commit references to research documentation containing code snippets. Use when writing technical docs with code examples, creating investigation/research docs that reference source files, user asks to "add permalinks" or "add GitHub links", documenting code research findings with file:line references, or creating audit trails needing permanent code references. Triggers on "add github links", "add permalinks", "link to source", "make code references permanent".
|
Add GitHub Permalinks
Add permanent GitHub file URLs to research documentation so code references don't break when files change.
Workflow
1. Identify Repositories
Scan the document for code references to determine which repositories are involved:
# Common patterns to detect:
repos/{repo}/path/to/file.rb:123 → submodule repo
app/models/user.rb:45 → current repo
commit abc123 in org/repo → external repo
2. Get SHA for Each Repository
cd repos/{repo} && git rev-parse HEAD
git rev-parse HEAD
3. Add Permalinks to Code Blocks
Transform code block comments from local paths to GitHub permalinks:
Before:
def example_method
end
After:
def example_method
end
4. Update Reference Tables
Convert plain file paths to clickable markdown links:
Before:
| File | Line | Content |
|---|
app/models/user.rb | 45 | method definition |
After:
5. Add Reference SHAs Header
Add a reference section at the top of Technical Notes or similar sections:
> **Reference SHAs (Permalinks):**
> - **{repo}**: [`{short_sha}`](https://github.com/{org}/{repo}/tree/{SHA}) (YYYY-MM-DD)
Permalink Format
https://github.com/{org}/{repo}/blob/{SHA}/{path}#L{start}-L{end}
| Component | Example | Notes |
|---|
| org | myorg | GitHub organization or username |
| repo | myrepo | Repository name |
| SHA | c617ebdcda... | Full or short (10+ chars) commit SHA |
| path | app/models/user.rb | File path from repo root |
| #L{n} | #L45 | Single line anchor |
| #L{n}-L{m} | #L45-L50 | Line range anchor |
Checklist
