mostafa-drz/code/project-updates

Project Updates

Draft Linear project status updates — one per project, in the team template (Done / In Progress / Next / Blockers) — from everything I did today, across every tool I use. Show drafts, capture edits, learn patterns.

Preferences

On startup, use the Read tool on ~/.claude/skills/project-updates/preferences.md. If not found, no preferences are set.

Learnings

On startup, use the Read tool on ~/.claude/skills/project-updates/learnings.md. If not found, treat as empty. These are accumulated patterns from past edits — apply them silently when drafting. Do not mention the learnings file to the user unless adding to it.

Context

On startup, use Bash to gather (skip any that fail):

• Current date: date +%Y-%m-%d
• Git user email: git config --global user.email
• GitHub username: gh api user -q .login 2>/dev/null
• Linear user (from MCP): mcp__claude_ai_Linear__get_user with self

Command routing

Check $ARGUMENTS:

• help → display help, stop
• config → interactive setup, stop
• reset → delete preferences.md (keep learnings and drafts), confirm, stop
• forget-learnings → delete learnings.md, confirm, stop
• show-learnings → print learnings.md contents, stop
• anything else (including empty) → run the skill

Flags

Parse from $ARGUMENTS:

• --since <time> — lookback window (e.g., 24h, 48h, yesterday, monday). Default: from preferences, else 24h.
• --projects <list> — comma-separated Linear project slugs/names to include (overrides default set).
• --project <slug> — shortcut for a single project.
• --sources <list> — comma-separated: linear,git,github,slack,notion,gmail,calendar. Default: all available.
• --dry-run — draft only; skip writing to drafts/ and skip learnings capture.
• --no-feedback — skip the per-draft feedback prompt.
• --format <style> — template (default: Done/In Progress/Next/Blockers) or narrative (paragraph style).

Help

Project Updates — Draft Linear project status updates from all your signals

Usage:
  /project-updates                         All projects I lead, last 24h
  /project-updates --since 48h             Last 48 hours
  /project-updates --project fast-signals  One specific project
  /project-updates --sources linear,git    Only these sources
  /project-updates --dry-run               Draft only, don't save
  /project-updates show-learnings          Print accumulated learnings
  /project-updates forget-learnings        Wipe learnings.md
  /project-updates config                  Set preferences
  /project-updates reset                   Clear preferences
  /project-updates help                    This help

Template (Done / In Progress / Next / Blockers):
  Done:
  In Progress:
  Next:
  Blockers:

Sources (auto-detected, graceful skip):
  linear    Assigned issues, project activity, comments, status updates
  git       Commits across configured repos (see `repos-root` + `default-repos` in preferences) touching project branches
  github    PRs opened, merged, reviewed; linked to Linear IDs
  slack     Mentions, threads where I participated
  notion    Pages I edited or that reference project IDs
  gmail     Threads I replied to
  calendar  Meetings attended (supplementary)

Current preferences:
  (read from preferences.md)

Config

Use AskUserQuestion for these:

Q1 — Default lookback window? Options: 24h (default), 48h, since last run, custom

Q2 — Which Linear projects do you lead or contribute to regularly? Free-text or multiSelect populated from list_projects (member == me). These become the default project set.

Q3a — Where do your local repos live? (repos-root) Free-text path. Default: ~/Dev/. The skill expects each configured repo to be a direct subdirectory of this root (e.g., <repos-root>/<repo-name>).

Q3b — Which local repos to scan for git history? (default-repos) Free-text comma-separated list of repo directory names under repos-root. No defaults — this is per-user. Example input: acme-frontend, acme-api, design-system.

Q4 — Which sources to include by default? (multiSelect)

• Linear (required)
• Git (local commits)
• GitHub (PRs)
• Slack (mentions)
• Notion (page edits)
• Gmail (thread replies)
• Calendar (meetings)

Q5 — Default output format? Options: template (Done/In Progress/Next/Blockers) (default) or narrative (paragraph)

Q6 — Auto-copy first draft to clipboard? Yes / No (default: No)

Q7 — Confirm: this skill NEVER auto-posts to Linear, right? Options: Correct — always show me first (expected), Actually, allow auto-post with confirmation (switches behavior)

Save to ~/.claude/skills/project-updates/preferences.md.

Reset

Delete ~/.claude/skills/project-updates/preferences.md. Confirm: "Preferences cleared. Learnings and drafts preserved."

Forget-learnings

Delete ~/.claude/skills/project-updates/learnings.md. Confirm: "Learnings wiped. Future drafts will start fresh."

Show-learnings

Read ~/.claude/skills/project-updates/learnings.md and print its contents verbatim. Then stop.

First-time detection

If no preferences.md exists, show: "First time using /project-updates? Run /project-updates config to set defaults, or continue — I'll auto-detect projects from Linear (assignee == you) and use sensible defaults."

Then proceed.

Workflow

1. Resolve time window

Priority:

1. --since flag
2. last-run-timestamp in preferences (if since last run mode)
3. Default from preferences, else 24h

Compute absolute ISO timestamps (since_iso, until_iso=now).

2. Resolve project set

Priority:

1. --project <slug> — one project
2. --projects a,b,c — explicit list
3. default-projects from preferences
4. Fallback: query mcp__claude_ai_Linear__list_projects with member: "me", filter to active projects (state != completed/cancelled)

For each project, collect: id, name, slug, url, and the most recent existing status update (via get_status_updates filtered to that project, limit 3) — used as anchor ("progress since last update").

3. Detect available sources

Apply --sources override if given, else use configured set intersected with runtime availability:

• git — verify at least one configured repo exists under <repos-root>/ (from preferences). If repos-root is unset, skip git source with a one-line note.
• github — gh auth status must succeed
• linear, notion, slack, gmail, calendar — ping the MCP (try one cheap read; skip on failure)

Report once at top of output:

Sources: linear, git, github, slack  |  Skipped: notion (not configured), gmail (no matches today)

4. Gather signals per project (parallel)

For each project, run collectors in parallel. All collectors must be scoped to [since_iso, until_iso].

Linear

• list_issues with project: <id>, updatedAt: -P<window>, order by updatedAt
• For each issue updated in window: list_comments to extract comments by me or tagged @me
• Filter to: status transitions, my comments, my assignments/reassignments, completed issues
• Also query get_status_updates (type: project, project: id) to see what the last posted update already covered — DO NOT re-report work already posted

Git (across configured repos)

For each repo in config:

cd <repo> && git log --since="<since_iso>" --author="<email>" --pretty=format:'%h|%s|%ad' --date=iso 2>/dev/null

Cross-reference commit messages / branch names for Linear issue IDs (regex [A-Z]{2,4}-\d+). Bucket each commit to a project by the issue ID → project mapping from Linear.

Also check uncommitted WIP: git status --short per repo (surface as "in progress").

GitHub

gh pr list --author @me --state all --search "updated:>=<since_iso>" --json number,title,state,url,mergedAt,headRefName,body
gh pr list --search "review-requested:@me updated:>=<since_iso>" --state all --json number,title,state,url

Parse PR body/branch for Linear IDs → bucket to project. Distinguish: opened, merged, in review (mine), reviewed-by-me (someone else's).

Slack

Use slack_search_public_and_private with query from:@me after:<date> and secondary queries per project (project name, Linear ID prefix). Keep to threads with substantive messages (>= 20 chars, not just reactions).

Notion

Use notion-search with project name as query, filter to pages edited in window. Fetch each to extract the change.

Gmail (optional)

search_threads with after:<date> from:me. Bucket by recipient/project only if the project name or Linear ID appears.

Calendar (optional)

list_events for meetings in window where user attended. Supplementary context for "In Progress" (e.g., "Aligned with <reviewer> on <topic>").

5. Synthesize drafts

For each project, feed all collected signals + the last posted status update + the learnings file into the draft model. Produce one draft per project using the user's preferred format.

Template format (default):

## {Project Name} ({slug})

**Done:**
- <concrete thing shipped, with PR# or Linear ID>

**In Progress:**
- <current work, with ownership if shared>

**Next:**
- <next concrete step, not vague>

**Blockers:**
- <blocker with who/what needed to unblock, or "none">

Drafting rules (hard):

• Every bullet ≤ 1 line. If it needs two, split or simplify.
• Always include Linear IDs and PR numbers when available (link markdown).
• Never claim work someone else led. Co-ownership → name the other person.
• Don't repeat content from the last posted status update — start from "since <last update date>".
• Omit empty sections silently (e.g., no "Blockers: none" unless the user's learnings say to keep it).
• Apply every rule currently in learnings.md.

Narrative format (if selected): 2-4 sentence paragraph per project, same rules.

6. Present drafts

Show drafts one project at a time with source-count footer:

Project: <Project Name from Linear>
Since: <ISO timestamp of your last update>
Signals: <N Linear comments, M PRs merged, K PR in review, J Slack threads>

Done:
- <repo> #<PR> merged — <one-line user-visible summary from the PR body>
- <repo> #<PR> opened, in review (<one-line summary>)

In Progress:
- <currently-open work item, anchored to a Linear issue or PR>

Next:
- <upcoming work, scoped from `next` Linear column or open PRs>

Blockers:
- <blocker, with the responsible reviewer/owner if known>

[Linear: https://linear.app/<linear-org>/project/<slug>]

7. Feedback capture per draft

For each draft, prompt via AskUserQuestion unless --no-feedback:

• Accept — copy to clipboard, move on
• Edit — user provides corrected text; skill diffs original vs edit and extracts patterns
• Skip — no copy, move on
• Open Linear — print the project activity URL for pasting

On Edit:

1. Accept the user's rewritten draft
2. Compare original vs edited line-by-line
3. For each meaningful delta (phrasing change, added detail, removed content, reordering), ask:

   "Detected pattern: <concise description>. Save as learning? (y / n / reword)"

4. If y or reword, append to learnings.md under the right section (Style / Phrasing / Per-project / Per-source). Include date.
5. Skip trivial deltas (typos, whitespace).

Copy the edited draft to clipboard with pbcopy if preference says auto-copy, or after "Accept".

8. Save daily draft history

Unless --dry-run, write all drafts (original + edited) for the day to:

~/.claude/skills/project-updates/drafts/<YYYY-MM-DD>.md

This is the audit trail — useful for debugging bad learnings later. Append mode if the file exists (multiple runs per day).

9. Update preferences

• Set last-run-timestamp to now (for since last run mode)
• If user consistently skipped a source, nudge: "You've skipped Notion 5 runs in a row — remove from default sources? [y/n]"
• If user always edits in the same direction, confirm the pattern is captured in learnings.md

10. Summary

End with a one-line tally:

Drafted 3 projects · 2 accepted, 1 edited · 2 new learnings saved · Run again tomorrow to continue.

Learnings file format

~/.claude/skills/project-updates/learnings.md:

# /project-updates Learnings
Last updated: YYYY-MM-DD

## Style
- <rule> — saved <date>

## Phrasing
- <rule> — saved <date>

## Per-project
### <project slug>
- <rule> — saved <date>

## Per-source
### git
- <rule>
### linear
- <rule>

## Corrections log
- <date>: <what was corrected and what pattern was learned>

When the file exceeds ~200 lines, consolidate duplicates and archive the rest to learnings.archive.md (do this silently, mention once).

Principles

• Never auto-post. Show the draft. User pastes. Non-negotiable — violates the user's stated constraint.
• Template is law. Done / In Progress / Next / Blockers in that order, every time, unless --format narrative. The four-section template is the default; configure via preferences if your team uses a different ordering.
• Anchor to last update. Every draft starts from "what changed since the last posted status update" — no duplicate work credited twice.
• Graceful degradation. If Slack/Notion/Gmail are unavailable, skip them. The draft can be made from Linear + git alone.
• Learnings are earned, not assumed. Only add to learnings.md when the user explicitly confirms a pattern, or when a correction is repeated across runs. Avoid cluttering the file with one-off edits.
• Claim only your work. If a PR was reviewed by me but authored by someone else, it's "reviewed X's PR", not "shipped X". Co-ownership always named.
• Terse beats complete. One-line bullets win. Detail belongs in the linked PR or ticket.