From john-skills
Creates and maintains DEVLOG.md logging project evolution, decisions, challenges from git repo, Claude chat history, planning docs. For progress updates, milestones.
npx claudepluginhub jbdamask/john-claude-skills --plugin john-skillsThis skill uses the workspace's default tool permissions.
Create and maintain `DEVLOG.md` in the project root. The devlog tells the story of the project - why it exists, how it evolved, what decisions were made and why, challenges encountered, and pivots taken. A reader should be able to read it end-to-end and understand the project's journey. It should be detailed enough to reconstruct the development narrative, but not an exhaustive transcript.
Logs factual progress from git work sessions (detected via 3-day gaps) to a global markdown file after sprints, phases, or milestones. Useful for 'document my progress' or post-repo work.
Automates isolated daily dev logs for multi-project development by summarizing conversation progress, Git commits, and changes into project-specific Markdown files.
Orchestrates GitHub issues/PRs/branches as knowledge graph for traceability in planning, brainstorming, designs, architectural decisions, session resumption. /shiplog.
Share bugs, ideas, or general feedback.
Create and maintain DEVLOG.md in the project root. The devlog tells the story of the project - why it exists, how it evolved, what decisions were made and why, challenges encountered, and pivots taken. A reader should be able to read it end-to-end and understand the project's journey. It should be detailed enough to reconstruct the development narrative, but not an exhaustive transcript.
First, establish the current working directory and derive the chat history path:
pwd
Convert the project path to the chat history directory name by replacing / with -:
/Users/johndamask/src/tries/2026-01-08-myproject~/.claude/projects/-Users-johndamask-src-tries-2026-01-08-myprojectBefore gathering information, verify you can access the key sources. If any are unavailable, ask the user for guidance.
Check for:
.git directory or git status)~/.claude/projects/<converted-path>/).claude/, project root, or docs folders)If git is not found, ask the user: "I don't see a git repository here. How is source code tracked for this project?" The project may use a different VCS, or this may be a subdirectory of a larger repo.
Collect information from all available sources:
Search for planning documents in the project:
find . -name "*.md" -type f | xargs grep -l -i "plan\|implementation\|architecture" 2>/dev/null | head -20
Also check for Claude plan mode artifacts (often in .claude/ or project root). If planning documents exist, summarize key decisions and link to them in the devlog.
Read conversation history from the project's chat directory. Focus on sessions since the last devlog entry:
ls -lt ~/.claude/projects/<converted-path>/*.json 2>/dev/null | head -10
Handling Large History Files:
Chat history files can grow large and may not fit entirely in context. When this happens:
Check file size first:
wc -l ~/.claude/projects/<converted-path>/*.json
Process in chronological chunks if files are large:
head and tail with line offsets to read manageable sections (e.g., 500-1000 lines at a time)Use dates to detect gaps:
YYYY-MM-DD headerIterative parsing strategy:
# Read first chunk (oldest)
head -n 1000 <history-file>
# Read subsequent chunks
tail -n +1001 <history-file> | head -n 1000
# Continue until you've covered the full date range
Fill gaps systematically: If the devlog has missing date ranges, work through them chronologically. If context limits force you to stop before completing all gaps, document where you stopped so the next update can continue from there.
Parse the JSON files to extract:
First, verify git is available:
git status 2>/dev/null || echo "NOT_A_GIT_REPO"
If git is not found: Ask the user how source code is tracked. They may use a different VCS (Mercurial, SVN, etc.), or this directory may be part of a larger repository. Don't assume - ask.
If git is available: Review commits since the last devlog entry (check the "Last Updated" date in DEVLOG.md, or use a reasonable default):
git log --oneline --since="<last-devlog-date>" 2>/dev/null || git log --oneline -30
For more detail on specific commits:
git log --pretty=format:"%h - %s (%ai)" --since="<last-devlog-date>"
If the devlog hasn't been updated in a long time, you may need to cover a larger range. Focus on commits that represent meaningful changes rather than trying to document everything.
Issues provide valuable context for the devlog - they capture the "why" behind work, discussions, and decisions.
Discover the issue tracker:
Check for common indicators in the project:
.github/ directory → likely GitHub Issueslinear.json or .linear/ → Linearbeads.json or .beads/ → Beads (bd list command).jira/ or Jira references in commits → Jiranotion.json → NotionCheck git remote for GitHub/GitLab:
git remote -v 2>/dev/null
If no tracker is obvious, ask the user: "Where are issues tracked for this project? (GitHub, Jira, Linear, Notion, Beads, or something else?)"
Connecting to issue trackers:
gh CLI if available (gh issue list, gh issue view <number>)bd list and bd show <id>If the issue tracker requires a connection that isn't available:
Handling large issue histories:
Apply the same chunked reading strategy as with chat history:
Extract from issues:
Create or append to DEVLOG.md in the project root.
Each entry should include a date header and narrative content. Use subsections only when they add clarity - simple entries don't need heavy structure.
Minimal entry:
## YYYY-MM-DD - [Brief Title]
[2-4 sentences describing what was accomplished, decided, or learned. Include the *why* behind decisions.]
---
Detailed entry (for significant milestones, pivots, or complex decisions):
## YYYY-MM-DD - [Brief Title]
### Summary
[2-4 sentences describing what was accomplished or decided]
### Details
- [Specific changes, decisions, or discoveries]
- [Problems encountered and how they were resolved]
- [Key code or architectural decisions with brief rationale]
### References (optional - include only if genuinely useful)
- Planning doc: [link if applicable]
- Related commits: [commit hashes if relevant]
- Related issues: [issue numbers/links if relevant]
---
Entry granularity: Create entries at natural breakpoints - completing a feature, making a significant decision, encountering and resolving a major problem, or pivoting direction. Not every work session needs an entry, but significant events should be captured close to when they happen.
Include:
Omit:
Remember: The devlog is a narrative, not a changelog. Include technical details, but write them as part of a story. Someone reading it should come away understanding the project's journey - its origin, evolution, challenges overcome, and lessons learned - and stay engaged while reading.
New entries go at the end of the file (chronological order). The devlog tells the story of the project from beginning to present - a reader should be able to read it top-to-bottom and understand the journey: why the project was created, what's been done, key design decisions, challenges, pivots, and current state.
# Development Log - [Project Name]
## About This Project
[Factual description of what the project does and why it exists. Write from the product perspective, not technical implementation. Answer: What problem does this solve? Who is it for? What does it do?]
**Status:** [Active | Maintenance | Complete]
**Started:** YYYY-MM-DD
**Last Updated:** YYYY-MM-DD
Status definitions:
- **Active** - Under active development, features being added
- **Maintenance** - Stable, only bug fixes and minor updates
- **Complete** - No further development planned
---
## YYYY-MM-DD - Project Inception
[Why was this project started? What problem needed solving? What was the initial vision?]
---
## YYYY-MM-DD - [Milestone or Decision Title]
[What happened, what was decided, why it matters. Simple entries are fine.]
---
## YYYY-MM-DD - [Major Pivot or Complex Change]
### Summary
[Overview of the change]
### Details
- [Key decisions and rationale]
- [Challenges encountered]
---
The "About This Project" section should be:
Bad: "A cutting-edge, blazingly fast microservices architecture leveraging React and Node.js" Good: "A task management app for small teams who need to track work across multiple projects without the complexity of enterprise tools"
The devlog entries themselves should include technical details - architecture decisions, technology choices, implementation challenges - but written as a narrative, not a dry list. A good devlog is readable and has flow. Someone should be able to read it end-to-end and stay engaged.
Avoid this (dry bullet list):
- Added Redis caching
- Switched from REST to GraphQL
- Fixed N+1 query problem
- Updated Node to v20
Prefer this (narrative with technical substance):
Switched the API from REST to GraphQL after realizing our mobile app was making
12 separate requests to render the dashboard. GraphQL let us collapse that to one
request, but introduced an N+1 query problem that was hammering the database. Added
Redis caching for the user-preference lookups which were the main culprit - response
times dropped from 800ms to 120ms.
Both versions contain technical details, but the second tells a story: there was a problem, a solution was tried, a new problem emerged, it was solved, and here's the result.