DevDay

DevDay — Project-Agnostic Dev Session Journal

A two-command journal that turns a working day in any git repo into a durable, skimmable record. You write the work. Git captures the evidence. DevDay turns both into a journal your future self (and your team) will actually re-read.

The only requirement is that you're inside a git repository. Everything else is auto-detected on first run and cached.

---

The Two Commands

Command	Purpose	Speed	When to run
/devday-log	Append a timestamped checkpoint	Seconds	After every meaningful chunk of work
/devday	Synthesize today's full report	~30s	End of day, or when you wrap a session

/devday-log is the append-only data feed. /devday is the read-only synthesizer. You can run /devday-log ten times a day and /devday once. The synthesizer reads the checkpoints AND the git log and produces the final artifact.

---

Phase 0 — Orient (runs on first invocation per project)

This phase is mandatory on first run and idempotent thereafter. It establishes how the skill behaves inside this specific repository, then caches the result so future runs skip straight to the work.

Step 0.1 — Verify git

git rev-parse --is-inside-work-tree

If this fails or returns false, abort with a one-line message: DevDay requires a git repository. Run \git init` first, or change into a project directory.` Do not try to operate without git — git is the evidence layer.

Step 0.2 — Locate project root and load cache

PROJECT_ROOT=$(git rev-parse --show-toplevel)
CONFIG_PATH="$PROJECT_ROOT/.devday/config.json"

If $CONFIG_PATH exists, read it and skip to Phase 1 or Phase 2. The config is project-local, committed to git, and shared across the team.

Step 0.3 — Detect project name (in priority order)

Stop at the first match.

1. package.json → name field
2. pyproject.toml → [project] name or [tool.poetry] name
3. Cargo.toml → [package] name
4. go.mod → first module line, last path segment
5. pom.xml → <artifactId>
6. Gemfile (Ruby) → directory basename
7. Repository remote URL → last segment minus .git
8. Fallback: basename "$PROJECT_ROOT"

Strip scopes (@org/name → name) and lowercase if needed. This is just a display label; don't agonize.

Step 0.4 — Detect or create the devlog directory

Probe in priority order. Stop at the first directory that exists.

1. docs/devlogs/
2. docs/devlog/
3. devlogs/
4. devlog/
5. .devlogs/
6. .claude/session-reports/

If none exists, create docs/devlogs/ when a docs/ directory is already present, otherwise create .devlogs/. The directory does not need to be in .gitignore — these logs are valuable history.

Step 0.5 — Detect default branch

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@'

Fallback chain: main → master → trunk → current branch.

Step 0.6 — Optional: read project tagline

Look for a one-line description in this order. Truncate to 80 chars. This shows up in the log headers as ## Project: <name> — <tagline>.

1. package.json → description
2. pyproject.toml → description
3. Cargo.toml → description
4. README.md → first paragraph after the H1 (best-effort)
5. Empty (skip)

Step 0.7 — Write the config

Create .devday/config.json at project root:

{
  "version": 1,
  "projectName": "BORG",
  "tagline": "Stafrænt þróunarumhverfi",
  "logDir": "docs/devlogs",
  "defaultBranch": "main",
  "fileNamingScheme": "yearMonth",
  "orchestrator": "Magnus Smárason | smarason.is",
  "createdAt": "2026-05-19T13:00:00Z"
}

fileNamingScheme options:

• "yearMonth" — <logDir>/YYYY/MM-monthname/devday_YYYYMMDD.md (default; scales)
• "flat" — <logDir>/devday_YYYYMMDD.md (smaller projects)

If a project already has many existing logs under one scheme, respect it — don't silently migrate. Detect by looking for files matching either pattern under logDir/.

orchestrator (optional). Free-text string — a name, an email, a handle, a tag. When set, every log header includes an **Orchestrator:** line beneath the project title (see Step 1.2 and Step 2.3). The skill never auto-fills this field; if the user hasn't asked for it explicitly, leave it absent and omit the header line. The point is enactment — when set, every devlog is signed by the human responsible for the AI-assisted work captured inside it. This is opt-in; many projects won't want it.

Step 0.8 — Confirm orientation in one line

After Phase 0, print exactly one line to the user, then proceed to whatever they actually asked for:

DevDay oriented: <projectName> @ <logDir>/ (branch: <defaultBranch>). Config cached at .devday/config.json.

If config already existed, skip this line entirely — orient is silent on subsequent runs.

---

Phase 1 — /devday-log (Append a Checkpoint)

Goal: capture what's happening right now in a few seconds. No synthesis. No git log walking. Just a timestamped snapshot of context.

Step 1.1 — Run config-load + git context in parallel

# All in one parallel batch:
git log --oneline -8 --format="%h %s (%ar)"
git diff --stat HEAD~3 HEAD 2>/dev/null
git branch --show-current
date "+%H:%M"

Step 1.2 — Resolve today's log file

<logDir>/YYYY/MM-monthname/devday_YYYYMMDD.md

Where MM-monthname is e.g. 05-may, 12-december. Lowercase English month names.

Examples:

• docs/devlogs/2026/05-may/devday_20260519.md
• .devlogs/2026/01-january/devday_20260108.md

If fileNamingScheme is "flat", just <logDir>/devday_YYYYMMDD.md.

Create parent directories if missing. If the file doesn't exist, write this header first:

# Dev Day Log: YYYY-MM-DD
## Project: <projectName> — <tagline>

**Orchestrator:** <orchestrator>   <!-- emit this line only if config.orchestrator is set; omit otherwise -->

---

Step 1.3 — Append the checkpoint

Never overwrite existing content. Append:

## HH:MM — <6-12 word summary of what was just done>

**Branch:** `<current-branch>`
**Recent commits:**
- `<hash>` <subject>
- `<hash>` <subject>

**What's happening:**
<2-4 sentences. What problem is being solved right now? What just got done?
What's the immediate next step? Capture decisions, blockers, anything worth remembering.>

**Files in focus:**
- `<path>` — <why>
- `<path>` — <why>

---

If the user passed a note as argument (/devday-log "just finished the migration"), use it as the summary line and the headline of "What's happening". Still pull the rest from git.

Step 1.4 — Confirm

One-line response:

Logged @ <HH:MM> → <relative-path-to-log-file>. <N> entries today. Run /devday at end-of-day for the full report.

---

Phase 2 — /devday (Synthesize the Day)

Goal: produce a single, polished markdown report that captures today's work in a form worth re-reading next week, next quarter, or by a stranger.

Step 2.1 — Load context (parallel)

Run these simultaneously:

git log --all --since="6am" --pretty=format:"%h|%an|%ai|%s|%D" --no-merges
git log --all --since="6am" --until="now" --shortstat --no-merges
git diff --stat HEAD~10 HEAD 2>/dev/null
git status --short
git branch --show-current

Read today's existing log file (if any) — its ## HH:MM — checkpoint entries are the narrative backbone.

Step 2.2 — Decide path

If today's log exists: read it. Extract all ## HH:MM — checkpoints. The synthesis enriches the file — preserves checkpoints verbatim, adds the structured sections around them.

If no log file: generate from scratch using git history alone.

Step 2.3 — Synthesize

Write the report using this template. Treat checkpoints as authoritative narrative; git is evidence.

# Dev Day Log: <YYYY-MM-DD> (<weekday>)
## Project: <projectName> — <tagline>

**Orchestrator:** <orchestrator>   <!-- emit only if config.orchestrator is set -->

### Summary

<2-4 sentences. Major wins, bugs fixed, features shipped. Be specific. Use real numbers
and PR/commit references. If checkpoints exist, this paragraph reflects them; otherwise
it reflects the commit log.>

---

## Checkpoint Log

<If /devday-log entries exist, include them here verbatim under their timestamps.
Preserve formatting. If none exist, omit this entire section.>

---

## 📊 Commits Today

| Hash | Message | Time |
|------|---------|------|
| `abc1234` | feat: ... | 14:32 |

**By type:**
- **feat:** X  — **fix:** X  — **docs:** X  — **chore:** X — **other:** X

---

## ✅ Key Accomplishments

- <Specific thing completed>
- <Specific thing completed>
- <Specific thing completed>

---

## 🧠 Decisions Made

1. **Decision:** <what>
   **Why:** <rationale>
   **Impact:** <what it affects going forward>

---

## 🔄 Next Steps

- [ ] <Item to pick up next session>
- [ ] <Follow-up task>
- [ ] <Open question to resolve>

---

## 🎯 Session Quality

**Flow:** high / medium / low
**Blockers:** none / minor / significant
**Overall:** <one honest sentence>

---

## Session Summary

**Total Commits:** X
**Estimated Duration:** X hours (first commit → last commit)
**Files Modified:** X
**Lines:** +X / -X

**Final Verification:**
- ✅ <What's confirmed working>
- ✅ <Tests status>
- ✅ <Branch / PR status>

**Status:** <Overall project health — one line>

---

*Generated by DevDay v2 — <TIMESTAMP UTC>*

Step 2.4 — Categorize commits

Use conventional-commit prefixes (feat:, fix:, docs:, refactor:, test:, chore:, perf:, ci:, build:, style:, revert:). Commits without a recognized prefix go in Other. Don't moralize about non-conventional commits — just bucket them.

Step 2.5 — Estimate duration

First-commit-of-day timestamp → last-commit-of-day timestamp. Round to nearest 15 min.

If only one commit, report < 30 minutes. If commits span a multi-hour gap (> 90 min) with no checkpoints, call it out as "split sessions" in Session Quality.

Step 2.6 — Extract decisions

Look for decision indicators in commit messages and checkpoint entries:

• "chose X over Y", "decided to...", "switched from X to Y"
• "migrated to...", "replaced X with Y", "opted for..."
• Anything in a **Decision:** line inside a checkpoint

Promote these to the 🧠 Decisions Made section with rationale and impact filled from context.

Step 2.7 — Vibe / Session Quality heuristics

Signal	Flow	Blockers
Many short-interval commits, focused branch	High	—
Steady progress, some gaps	Medium	—
Long gaps, few commits, context switching	Low	—
Revert/fix loops visible in git log	—	Minor or Significant
Multi-attempt commits on same area	—	Minor
Clean linear history, green CI	—	None

Be honest. A medium-flow day with significant blockers is more useful than a fake "high-flow productive!" assessment.

Step 2.8 — Write the file

Overwrite today's log file with the enriched report. The checkpoints from Phase 1 are preserved verbatim under ## Checkpoint Log. Everything else is fresh synthesis.

Step 2.9 — Confirm

Print to user:

DevDay report → <relative-path-to-file>
  · <N> commits · <M> checkpoints · <K> files changed
  · <one-line summary>
  · Next: <single most important next step from the report>

---

Optional Integrations

DiaryLog / life-logging

After Phase 2, optionally offer to log the session:

{
  "time": "HH:MM",
  "what": "Dev session: <one-line summary>",
  "mood": "<inferred from vibe>",
  "tags": ["work", "development"],
  "note": "<path-to-report>"
}

Don't force this — only offer if a DiaryLog skill is detected in the environment.

Auto-commit the log

If the user has explicitly opted in (via .devday/config.json field "autoCommit": true), stage and commit the log:

git add <log-file>
git commit -m "docs(devday): YYYY-MM-DD session report"

Default is false. Many users prefer to commit logs as part of a batch.

Weekly review

A future /devweek could aggregate Mon–Sun logs into a weekly view. Out of scope here, but the file layout (YYYY/MM-monthname/devday_YYYYMMDD.md) is designed to support it.

---

Why These Defaults

• Git is the only hard requirement. Anything else (docs/, monorepo, single-package, Python, Rust, Node) is auto-detected.
• Config is committed. The team shares the convention. If you don't want the config in git, add .devday/ to .gitignore — Phase 0 will rerun and rebuild it.
• Checkpoints over end-of-day-only. Your future self forgets why by 18:00. Capture the why at 11:30 when it's fresh.
• Markdown, not HTML. Re-readable in GitHub, in your editor, in cat, on paper.
• Append-only checkpoint log. No risk of /devday-log corrupting an existing entry.
• Synthesizer is idempotent. Running /devday twice produces the same report.

---

Anti-patterns to avoid

• Don't run /devday-log to record trivia. "Started thinking about X" is noise. Record finished thoughts, finished work, finished decisions.
• Don't synthesize without checkpoints if the day was non-trivial. A 6-commit day with no checkpoints will produce a thin report — git messages alone miss the why.
• Don't put credentials in checkpoints. They land in git log once committed. Treat the log as you treat any committed source file.

---

Reference: file paths the skill writes

File	When	Notes
.devday/config.json	First run per project (Phase 0)	Commit it
<logDir>/YYYY/MM-monthname/devday_YYYYMMDD.md	Every /devday-log and /devday	Append-only via /devday-log; rewritten by /devday

---

Versioning

• v1.x — BORG-specific, Magnús's personal workflow at smarason.is / unak.is
• v2.0 — Generalized, project-agnostic. First-run Phase 0 Orient. Works in any git repo.

Issues, PRs, and ports welcome.

---

Created 2026-02-14 · Generalized 2026-05-19 · Magnús Smári Smárason · MIT