bettersense

A growing collection of Claude Code skills and subagents for the people responsible for building and leading in the age of AI — AI Product Managers, Engineering Managers, TPMs, and senior ICs leading without authority.

These aren't generic productivity prompts. They encode the actual frameworks, mental models, and operational modes that technical leaders use day-to-day:

• AI PMs: deciding whether a problem deserves AI in the first place, building eval harnesses before committing engineering, designing safety sandwiches around LLM calls, red-teaming before launch, translating model metrics into business outcomes
• Engineering managers: coaching without prescribing, running performance conversations, building promotion cases, designing growth plans for reports, diagnosing team health
• TPMs and senior ICs: leading across teams that don't report to you, influencing without authority, managing multi-team programs, navigating stakeholder complexity
• All of the above: stakeholder reflection, wins logging, self-reflection, cadence-driven insight that accumulates over months

Why this exists

Most "AI for technical leaders" tooling either over-promises ("AI writes your PRD!") or under-delivers (a chatbot that doesn't know what an eval harness is). This repo takes a different bet: give Claude Code a small, opinionated set of skills and subagents that match how working technical leaders actually think, and let the harness route to the right one automatically based on what you're doing.

Each skill is a reusable framework Claude consults when context matches. Each subagent is a focused operational mode you can invoke explicitly or let Claude delegate to.

What's inside

bettersense/
├── plugin/
│   ├── monitors/
│   │   └── monitors.json
│   ├── bin/
│   │   └── check-wins-cadence
│   ├── skills/
│   │   ├── ai-pm-frameworks/SKILL.md
│   │   ├── coaching-mode/SKILL.md
│   │   ├── decision-log/SKILL.md
│   │   ├── demo-prep/SKILL.md
│   │   ├── engineering-health/SKILL.md
│   │   ├── feedback-frameworks/SKILL.md
│   │   ├── glue-audit/SKILL.md
│   │   ├── hiring-craft/SKILL.md
│   │   ├── impact-audit/SKILL.md
│   │   ├── influence-without-authority/SKILL.md
│   │   ├── leadership-os/SKILL.md
│   │   ├── manage-glue-workers/SKILL.md
│   │   ├── metrics-design/SKILL.md
│   │   ├── one-on-one-prep/SKILL.md
│   │   ├── patterns-watch/SKILL.md
│   │   ├── performance-management/SKILL.md
│   │   ├── premortem/SKILL.md
│   │   ├── prioritization-frameworks/SKILL.md
│   │   ├── product-pulse/SKILL.md
│   │   ├── psychological-safety/SKILL.md
│   │   ├── promo-case-glue/SKILL.md
│   │   ├── pulse-synthesize/SKILL.md
│   │   ├── read-the-room/SKILL.md
│   │   ├── report-career-architect/SKILL.md
│   │   ├── report-promo-case/SKILL.md
│   │   ├── self-reflect/SKILL.md
│   │   ├── stakeholder-due/SKILL.md
│   │   ├── stakeholder-manage/SKILL.md
│   │   ├── stakeholder-reflect/
│   │   │   ├── SKILL.md
│   │   │   └── questions.json
│   │   ├── stakeholder-register/SKILL.md
│   │   ├── stakeholder-synthesize/SKILL.md
│   │   ├── strategy-doc/SKILL.md
│   │   ├── team-charter/SKILL.md
│   │   ├── team-check-in/SKILL.md
│   │   ├── team-close-gap/SKILL.md
│   │   ├── team-diagnosis/SKILL.md
│   │   ├── team-lifecycle/SKILL.md
│   │   ├── team-style-inventory/SKILL.md
│   │   ├── user-profile/SKILL.md
│   │   ├── wins-curate/SKILL.md
│   │   ├── wins-due/SKILL.md
│   │   ├── wins-log/SKILL.md
│   │   └── workload-equity/SKILL.md
│   └── agents/
│       ├── the-architect.md
│       ├── the-career-coach.md
│       ├── the-data-storyteller.md
│       ├── the-discovery-facilitator.md
│       ├── the-eval-designer.md
│       ├── the-explainer.md
│       ├── the-gtm-planner.md
│       ├── the-incident-responder.md
│       ├── the-postmortem-facilitator.md
│       ├── the-program-manager.md
│       ├── the-prompt-critic.md
│       ├── the-red-teamer.md
│       ├── the-reducer.md
│       ├── the-research-synthesizer.md
│       ├── the-retro-facilitator.md
│       ├── the-rfc-reviewer.md
│       ├── the-scientist.md
│       ├── the-slo-designer.md
│       ├── the-spec-writer.md
│       ├── the-status-crafter.md
│       ├── the-translator.md
│       └── the-vendor-evaluator.md

Skills

Subagents

Install

Three install paths, in order of preference.

Plugin marketplace (easiest)

Claude Desktop app:

1. Click Customize in the left sidebar
2. Click + next to "Personal plugins" → choose Add marketplace
3. Enter shwetank/bettersense and click Sync
4. Go to Plugins → Code tab, find Bettersense, and click + to install it

Claude Code CLI (terminal):

/plugin marketplace add shwetank/bettersense
/plugin install bettersense@bettersense

To update later: /plugin marketplace update bettersense

Note: The /plugin commands only work in the terminal CLI. Pasting them into the Desktop app chat does nothing — use the GUI steps above instead.

Run /bettersense:start in a new chat to verify and get oriented.

Symlink-based install (recommended for development / standalone)

macOS / Linux / WSL:

git clone https://github.com/shwetank/bettersense.git
cd bettersense

# Install at user scope (available in every project):
scripts/install.sh

# Project scope instead (just this repo):
scripts/install.sh --scope=project

Windows (PowerShell): Requires Developer Mode (Settings → System → Developer Mode) or admin elevation for symlink creation.

git clone https://github.com/shwetank/bettersense.git
cd bettersense
.\scripts\install.ps1           # user scope
.\scripts\install.ps1 -Scope project

The script creates symlinks from ~/.claude/{skills,agents}/ (or ./.claude/... for project scope) back into this repo. Three benefits:

1. Updates are free — git pull updates your installed skills automatically.
2. You can identify bundle items at a glance — macOS/Linux:

   find ~/.claude/skills ~/.claude/agents -maxdepth 2 -type l -lname "*bettersense*"

Windows (PowerShell):

   Get-ChildItem "$HOME\.claude\skills","$HOME\.claude\agents" | Where-Object { $_.LinkType -eq 'SymbolicLink' -and $_.Target -like '*bettersense*' }

1. Clean uninstall — scripts/uninstall.sh (or uninstall.ps1 on Windows) removes only items that are symlinks into this repo. Skills you wrote yourself or installed from elsewhere are untouched.

The script will prompt before doing anything. Existing skills with the same name are skipped by default; pass --force (bash) or -Force (PowerShell) to overwrite.

Alternative: manual copy

If you prefer copies over symlinks (no admin needed, frozen snapshot):

macOS / Linux / WSL:

cd bettersense/plugin
mkdir -p ~/.claude/skills ~/.claude/agents
cp -r skills/* ~/.claude/skills/
cp agents/*.md ~/.claude/agents/

Windows (PowerShell):

cd bettersense\plugin
New-Item -ItemType Directory -Force "$HOME\.claude\skills","$HOME\.claude\agents"
Copy-Item -Recurse skills\* "$HOME\.claude\skills\"
Copy-Item agents\*.md "$HOME\.claude\agents\"

Tradeoff: no automatic updates, and identifying bundle items later requires consulting MANIFEST.md at the repo root.

Identifying bundle items

The repo root MANIFEST.md lists every skill and agent in the bundle by name with a one-line description. Use it as your reference for "is this skill mine, or part of this bundle?" — especially useful if you installed via cp and don't have the symlink trail to follow.

Verifying

Verify with /agents inside Claude Code — the 22 subagents should appear. Skills auto-load when prompts match their description; you can also trigger them explicitly with /<skill-name> (e.g. /ai-pm-frameworks, /decision-log, /leadership-os, /stakeholder-reflect, /wins-log, /coaching-mode, /read-the-room, /user-profile, /strategy-doc, /product-pulse).

Updating skills after changes

Two layers — disk and runtime — and they have different answers.

On disk:

• Symlink install: changes are instant. The file Claude Code reads from ~/.claude/skills/<name>/SKILL.md is the same file as <repo>/.../skills/<name>/SKILL.md. Edit the repo, no re-install step needed. git pull to take upstream updates.
• Manual `cp` install: you copied the file once; subsequent repo edits don't propagate. Either re-copy manually, or — better — run scripts/install.sh <variant> --force to replace copies with symlinks and switch to the auto-update path going forward.

Inside Claude Code (the runtime layer): The harness's caching semantics aren't comprehensively documented. Best working model:

• Editing the body of an existing skill (operating principles, examples, etc.) — usually picked up on the next invocation, since Claude reads the skill file when it routes into or runs the skill.
• Changing the `description` in frontmatter — may or may not affect auto-routing within an active session. The routing layer may have loaded the old description at session start. New sessions definitely see the update.
• Adding a new skill — the routing layer needs to discover it. Reliable in new sessions; may not be in your current one.
• Removing a skill, renaming it, or changing the `name` field — needs a restart. The routing layer carries stale state otherwise.

Safe rule: start a new Claude Code session after any non-trivial change. Cheapest way to guarantee the routing layer is fresh.

Verifying a change actually took effect: add a unique visible marker temporarily in the skill's operating principles, e.g.:

- **ALWAYS PREFIX YOUR FIRST RESPONSE WITH "TESTMARKER-2026-05-04"**

Invoke the skill; if you see the marker, the change is live. Remove it once confirmed.

Practical rhythm:

1. Install once via scripts/install.sh (symlinks).
2. Edit skills in the repo whenever you want to tune them.
3. Start a new Claude Code session after non-trivial edits.
4. git pull to take upstream updates — instant, since you're on symlinks.

Uninstall

macOS / Linux / WSL:

scripts/uninstall.sh                  # removes symlinks from ~/.claude/
scripts/uninstall.sh --scope=project  # removes from ./.claude/ instead
scripts/uninstall.sh --dry-run        # preview without removing
scripts/uninstall.sh --hard-uninstall # also offer to remove copies (one prompt per item)

Windows (PowerShell):

.\scripts\uninstall.ps1
.\scripts\uninstall.ps1 -Scope project
.\scripts\uninstall.ps1 -WhatIf        # preview without removing
.\scripts\uninstall.ps1 -HardUninstall # also offer to remove copies

Your reflection data at ~/bettersense-work-reflections/ (or $HOME\bettersense-work-reflections\ on Windows) is not touched by uninstall. The data is yours; remove it manually if you want.

Setup: data directory, environment, and scheduling

The basic Install above gets the skills loaded. This section covers everything else: where private data lives, how the cadence-driven skills (stakeholder-due, wins-due, self-reflect, team-diagnosis) get wired to actually fire on schedule, and how to pair Claude Code's /schedule with your existing reminder system to make the cadence reliable.

Best experience: Claude Code Desktop app

The cadence-driven skills (stakeholder-due, wins-due, self-reflect, patterns-watch, product-pulse) give you their full value only when they run on a schedule — and the Claude Code Desktop app is the easiest way to set that up. Desktop Routines run on your machine, have full access to ~/bettersense-work-reflections/, and persist indefinitely with no expiry.

If you use Claude Code in the terminal instead, OS-level scheduling (cron / launchd / Task Scheduler) works just as well but requires more setup. Cloud routines cannot access your local files and will not work with bettersense. See §5 Wire up scheduled skills for details.

Quick setup checklist (5 minutes)

☐ Skills installed (see Install section above)
☐ Decide on data location: default ~/bettersense-work-reflections/ or set $BETTERSENSE_WORK_REFLECTIONS_HOME
☐ Run /user-profile once → creates the data directory + privacy notice + "who you are" anchor file
☐ Run /stakeholder-register once → registers your first stakeholder
☐ Run /strategy-doc once per product/area → creates the "what you're building" anchor (optional)
☐ Wire up the recurring schedules below (or skip if you only want on-demand use)
☐ Add matching calendar reminders so you actually see the scheduled output
☐ Verify with /agents and /schedule list (or by triggering one skill manually)

The rest of this section walks through each step with the exact commands.

1. Set up your profile

Start here. user-profile does two things in one step: it creates ~/bettersense-work-reflections/ (your private local data directory) and produces profile.md — the anchor file that tells other skills who you are so you never re-explain context.

set up my profile

A 5-10 minute interview capturing your role, level, company context, communication style, current strategic focus, and (optionally) stack. The skill shows you a one-time privacy notice and confirms before writing anything. Update on real role changes, not every week. Supports "alternate hats" for users with mixed roles (PM + EM, TPM + IC); the skill only asks if you bring it up.

Skills that read profile.md automatically: the-spec-writer, the-translator, the-explainer, report-promo-case, report-career-architect, metrics-design, coaching-mode, feedback-frameworks.

If you want the data directory somewhere other than `~/bettersense-work-reflections/`, set $BETTERSENSE_WORK_REFLECTIONS_HOME before running user-profile:

macOS / Linux / WSL:

export BETTERSENSE_WORK_REFLECTIONS_HOME="$HOME/Encrypted/bettersense-work-reflections"
# Persist: add to ~/.zshrc (macOS) or ~/.bashrc (Linux)

Windows (PowerShell):

$env:BETTERSENSE_WORK_REFLECTIONS_HOME = "$HOME\Encrypted\bettersense-work-reflections"
# Persist: [System.Environment]::SetEnvironmentVariable('BETTERSENSE_WORK_REFLECTIONS_HOME', "$HOME\Encrypted\bettersense-work-reflections", 'User')

2. Strategy doc (optional)

The second anchor file — ~/bettersense-work-reflections/strategy/<area-slug>.md — captures the strategic context for a product, area, or program: target problem, approach, personas, SMART metrics, 2-4 multi-month tracks, explicit "not working on" section, counter-metrics.

Skills that read it: the-spec-writer, prioritization-frameworks, metrics-design, product-pulse, pulse-synthesize.

#### strategy/<area-slug>.md — what you're building

~/bettersense-work-reflections/strategy/<area-slug>.md captures the strategic anchor for a product, area, or program: target problem, approach, personas, SMART metrics, 2-4 multi-month tracks, explicit "not working on" section, counter-metrics.

Skills that read it: the-spec-writer, prioritization-frameworks, metrics-design, product-pulse, pulse-synthesize.

You never need to invent a slug. Just describe your area in plain language when you invoke the skill — Claude generates the slug from what you say. For example:

The skill always confirms the slug with you before writing — one quick confirmation prevents a month of pulse reports accumulating in the wrong folder. And if a file already exists for that slug, the skill surfaces it first and asks whether you want to refresh it or create a separate file for a genuinely different area. It never silently overwrites.

For single-product users, one file at strategy/default.md is fine. For users running multiple lines (PM with two products, TPM coordinating across three programs, EM owning multiple services), one file per area.

To create:

draft a strategy doc for [area name]

Triggers strategy-doc — interview-driven, refusable on weak inputs ("vague metrics aren't ready"). Refresh on real triggers (planning round, missed bet, market shift), not on schedule.

If the strategy file is missing, the relevant skills work without it — outputs are just more generic. The skills won't pester you to set it up unless you raise the question.

3. Background monitor (zero-config wins cadence)

bettersense ships a background monitor that nudges you to log wins without any scheduling setup. It runs automatically whenever the plugin is active — no Desktop Routines, no cron, no /schedule.

What it does: At the start of each Claude Code session, check-wins-cadence checks wins.md for the last entry date. If more than 14 days have passed (configurable) and you haven't been nudged within that same window, Claude gets a single notification: "No wins logged in N days. Run /bettersense:wins-log to capture recent work before the details fade." One nudge per cooldown window, then silence.

Nothing to configure. The monitor is declared in plugin/monitors/monitors.json and the script lives in plugin/bin/check-wins-cadence (added to PATH when the plugin is active). It respects $BETTERSENSE_WORK_REFLECTIONS_HOME and is silent until wins.md exists (i.e., until you've run /wins-log at least once).

To adjust the cadence, set WINS_NUDGE_THRESHOLD_DAYS in your shell environment before launching Claude Code:

# Nudge every 4 weeks instead of 2
export WINS_NUDGE_THRESHOLD_DAYS=28

The cooldown is keyed to the same threshold, so a 28-day setting nudges at most once per 28-day window.

4. The cadence story (read this once)

Claude Code skills are stateless guides. They fire when you invoke them — either by typing something that matches their description, or by name. Cadence requires wiring them to a scheduler.

There are three schedulers — only two work for bettersense:

❌ Cloud routines run on Anthropic's servers with no access to your local files. If Claude asks you to "push the bettersense-work-reflections directory to a GitHub remote" when you try to schedule something, that's the cloud path — stop and use one of the local options below instead.

✅ Desktop scheduled tasks (best option) — created in the Claude Code Desktop app via Routines → New routine → Local. These run on your machine, have full access to ~/bettersense-work-reflections/, persist indefinitely with no expiry, and support any cadence (daily, weekly, biweekly, monthly, quarterly). They fire while the Desktop app is open. Requires the Desktop app.

✅ OS-level scheduling (cron / launchd / Task Scheduler) — works on any version, fires whether or not Claude Code is open, supports any cadence. Best for monthly and quarterly cadences or if you use Claude Code in the terminal rather than the Desktop app. See OS-level scheduling fallback below.

⚠️ Session-scoped tasks (created by asking Claude to schedule something in a terminal/CLI session) have a hard 7-day expiry. A biweekly task expires before its second firing. A monthly task expires before it ever fires. Don't use these for bettersense cadences.

`/loop` is for active work sessions — polling a build, watching a PR — not weekly cadences.

Three honest constraints regardless of which local approach you use:

• Output lives inside Claude Code or a log file. No mobile push, no email, no SMS — Claude Code is desktop/CLI/IDE.
• Desktop tasks only fire while Claude Code is running. If you close it Friday afternoon and don't reopen until Tuesday, the Friday task fires when you next resume that session (or not at all if the session expired).
• Cadence reliability scales with how often you open Claude Code. Daily users get the full benefit. Weekly users see things drift. Monthly users should treat the skills as on-demand only.

The fix for users who don't live in Claude Code: pair every scheduled task with a calendar reminder in the system you actually check. The calendar grabs your attention; Claude Code does the work.

5. Wire up scheduled skills

Use the Claude Code Desktop app for these. In the sidebar, click Routines → New routine → Local. Give it a name, write the instructions (what Claude should do when it fires), and set the schedule. The Desktop app offers Daily, Weekdays, and Weekly presets; for biweekly, monthly, or quarterly, just ask Claude in a Desktop session in plain language and it will set the cron expression.

If you use Claude Code in the terminal rather than the Desktop app, skip to the OS-level scheduling section below — that's the reliable fallback for any cadence.

Pick the routines that fit your workflow — none are required:

Note on plugin namespace: If you installed via --plugin-dir, skill names need the bettersense: prefix — e.g. /bettersense:wins-due. Adjust accordingly.

Pair each routine with a calendar reminder in whatever system you actually check. The calendar grabs your attention; Claude Code does the work.

6. OS-level scheduling fallback (no /schedule required)

If you don't have the /schedule skill installed and don't want to add it, OS-level scheduling works on every platform. You invoke claude headlessly with the skill as a prompt, and redirect output to a log file you can check later.

Create the log directory first:

# macOS / Linux / WSL
mkdir -p ~/bettersense-logs

# Windows (PowerShell)
New-Item -ItemType Directory -Force "$HOME\bettersense-logs"

macOS / Linux / WSL — cron:

# Edit your crontab
crontab -e

# Friday 4pm — wins nudge
0 16 * * 5  claude -p "run /bettersense:wins-due" >> ~/bettersense-logs/wins-due.log 2>&1

# Monday 9am — stakeholder due-list
0 9  * * 1  claude -p "run /bettersense:stakeholder-due" >> ~/bettersense-logs/stakeholder-due.log 2>&1

# Sunday 6pm — patterns watch
0 18 * * 0  claude -p "run /bettersense:patterns-watch" >> ~/bettersense-logs/patterns-watch.log 2>&1

# Monday 8am — product pulse (default area)
0 8  * * 1  claude -p "run /bettersense:product-pulse" >> ~/bettersense-logs/product-pulse.log 2>&1

If claude isn't found by cron, use the absolute path: run which claude in your terminal and substitute (e.g. /usr/local/bin/claude).

macOS — launchd (alternative to cron):

launchd survives sleep/wake cycles and respects login sessions better than cron. Create a .plist at ~/Library/LaunchAgents/ai.bettersense.wins-due.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>ai.bettersense.wins-due</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/claude</string>
    <string>-p</string>
    <string>run /bettersense:wins-due</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Weekday</key><integer>5</integer>
    <key>Hour</key><integer>16</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key>
  <string>/Users/YOUR_USERNAME/bettersense-logs/wins-due.log</string>
  <key>RunAtLoad</key><false/>
</dict>
</plist>

Replace /usr/local/bin/claude with which claude output and YOUR_USERNAME with your macOS username. Load it:

launchctl load ~/Library/LaunchAgents/ai.bettersense.wins-due.plist
launchctl list | grep bettersense  # verify

Duplicate the file for each skill, changing the Label, ProgramArguments, StartCalendarInterval, and StandardOutPath fields.

Linux — systemd user timers (alternative to cron):

More observable than cron — you can check status, last run time, and logs.

Create ~/.config/systemd/user/bettersense-wins.service:

[Unit]
Description=bettersense wins nudge

[Service]
Type=oneshot
ExecStart=/usr/local/bin/claude -p "run /bettersense:wins-due"
StandardOutput=append:%h/bettersense-logs/wins-due.log
StandardError=append:%h/bettersense-logs/wins-due.log

Create ~/.config/systemd/user/bettersense-wins.timer:

[Unit]
Description=Run bettersense wins nudge every Friday

[Timer]
OnCalendar=Fri *-*-* 16:00:00
Persistent=true

[Install]
WantedBy=timers.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable --now bettersense-wins.timer
systemctl --user list-timers  # verify

Use %h (expands to home directory) rather than ~ inside systemd unit files.

Windows — Task Scheduler (PowerShell):

$action = New-ScheduledTaskAction `
    -Execute "claude" `
    -Argument "-p `"run /bettersense:wins-due`""

$trigger = New-ScheduledTaskTrigger `
    -Weekly -DaysOfWeek Friday -At "4:00PM"

$settings = New-ScheduledTaskSettingsSet `
    -StartWhenAvailable -RunOnlyIfNetworkAvailable

Register-ScheduledTask `
    -TaskName "bettersense-wins-due" `
    -Action $action `
    -Trigger $trigger `
    -Settings $settings `
    -Description "bettersense weekly wins nudge"

Repeat for each skill, changing -TaskName, -Argument, and -Trigger. To list all registered bettersense tasks:

Get-ScheduledTask | Where-Object { $_.TaskName -like 'bettersense*' }

Prefer Task Scheduler over Windows Subsystem for Linux scheduling if you installed Claude Code natively on Windows. If you're running everything inside WSL, use the cron/systemd instructions above inside your WSL environment.

Caveats that apply to all platforms:

• Verify the headless flag. claude -p "<prompt>" is the non-interactive invocation. Run claude --help to confirm. If headless isn't supported, OS-level scheduling won't work — use the /schedule skill or on-demand-only.
• Authentication. If claude -p requires you to be logged in, scheduled runs need a valid session token. May fail silently if the token has expired.
• Debugging cron: grep CRON /var/log/syslog (Linux) or log show --predicate 'process == "cron"' (macOS). PATH issues are common — cron runs with a minimal environment.

OS-level scheduling is less integrated than /schedule (no /schedule list to manage routines inside Claude Code) but works without any extra plugin and is portable across machines.

6. Listing and managing your schedules

Inside Claude Code:

/schedule list

Shows all routines you've created. To remove one:

/schedule delete <id-or-description>

You can also edit a routine to change its cadence — see the /schedule skill's own help for specifics.

7. External reminder pairing (recommended)

The single best thing you can do to make cadence reliable is to add one recurring calendar event per `/schedule` routine in the calendar / task system you actually check. The pattern:

• The calendar event grabs your attention at the right moment.
• The event's body says: "Open Claude Code → /<skill-name>".
• Claude Code already has the scheduled output ready when you open it.

This is the closest you can get to the Voohy app's mobile-push experience, while still doing the depth work in Claude Code.

8. Cadence cheat sheet

Skills not in this table are on-demand only — they fire when you describe a situation that matches them (a hire decision, a hard 1:1 prep, a new spec, a demo, a customer interview synthesis, an RFC review, etc.).

9. Stakeholder lifecycle (after the initial register)

Reorgs happen, people change roles, colleagues leave. The stakeholder-manage skill handles every lifecycle operation after the initial stakeholder-register. It routes by natural language — there's no syntax to memorize. Some examples:

Two design opinions worth knowing before you use it:

• Archive ≠ delete. Most "remove" requests are actually archive. The skill defaults to archive and requires explicit override. Reflection history about a former colleague is often the most valuable record you'll have when calibrating future hires, references, or working with their replacement.
• Re-categorize preserves history. When a peer becomes your manager, you don't restart the file. The 18 months of accumulated reflections are more relevant in the new relationship, not less. The audit log explains the transition; the entries underneath stay intact.

The audit log lives in each stakeholder file as a ## Audit log section between Background and Reflections. You can hand-edit it; the skill doesn't enforce.

10. Verify the setup

Run each of these to confirm:

# Skills installed?
ls ~/.claude/skills/        # or .claude/skills/ for project-scope

# Agents installed?
ls ~/.claude/agents/

# Data directory exists with privacy README?
ls -la ~/bettersense-work-reflections/
cat ~/bettersense-work-reflections/README.md

Inside Claude Code:

/agents               # 22 subagents should appear
/schedule list        # your routines should appear here

Trigger a skill manually as a smoke test:

let me reflect on my manager

…should auto-route to stakeholder-reflect (or to stakeholder-register if you haven't registered the manager yet).

11. Maintenance

The system is low-maintenance but not no-maintenance. Once a quarter:

• Skim ~/bettersense-work-reflections/ — anything stale, anyone you've stopped tracking actively, anyone you should have added?
• Run /schedule list and prune routines you're no longer reading.
• Run /stakeholder-synthesize once over your full file to look for patterns you've missed.
• Re-read the question library at ~/.claude/skills/stakeholder-reflect/questions.json — the prompts that landed for you 6 months ago may not be the ones that land now.

If a /schedule cadence keeps producing output you ignore, kill it and re-think. A nudge you've stopped acting on is worse than no nudge — it teaches you to ignore the system.

How it's meant to be used

Drop into Claude Code and describe what you're working on the way you'd describe it to a teammate. The harness routes:

• "Users keep complaining the search results feel off — should we add an LLM reranker?" → the-reducer runs first, asks whether this is genuinely an AI problem.
• "Here are 40 customer interviews. What does this tell us?" → the-research-synthesizer finds themes, jobs, and contradictions, anchored to direct quotes.
• "Draft a PRD for the contract-summarization feature." → the-spec-writer produces a decision-ready spec with success metrics and scoped non-goals.
• "How do I know if this prototype is good enough to ship?" → the-eval-designer designs the golden set, rubric, and ship/rollback bars; the-scientist runs it.
• "Can you review this system prompt before we ship?" → the-prompt-critic walks through it like a senior engineer in a code review.
• "We're putting this in front of paying customers next week." → the-architect designs guardrails; the-red-teamer finds what breaks; demo-prep skill scripts the launch readout.
• "The model's hallucination rate just spiked in production." → the-incident-responder stabilizes, investigates, writes the blameless postmortem; the-translator handles the customer comms.
• "What should we measure to know this AI feature is actually working?" → metrics-design builds the four-layer tree with counter-metrics that catch the "engagement up, product worse" trap.
• "Sales needs a one-pager on how this works that won't oversell." → the-explainer writes audience-calibrated capability + limitations + safety, with a what-to-say / what-not-to-say guide.
• "Help me reflect on my new manager so I actually know what they need from me." → stakeholder-register sets up the file, stakeholder-reflect guides the first session, stakeholder-due surfaces what to revisit weekly.
• "Reorg happened — Jill is my manager now, and Draymond left for Stripe." → stakeholder-manage re-categorizes Jill across folders (history preserved) and archives Draymond (file kept for retrospection, no longer surfaced in active reflections).
• "Before my reports' performance reviews, what do I actually know about each of them?" → stakeholder-synthesize reads the files and produces dated, citation-backed reads — patterns, contradictions, blind spots — for each.
• "I just shipped contract-summarization to GA — log it before I forget." → wins-log captures it structurally (situation, action, impact, evidence, honest credit) and pushes back if the impact framing is vague.
• "Friday afternoon — did I do anything notable this week?" → wins-due probes by category (judgment, recovery, mentorship, range) because the generic question gets blank stares.
• "I have a behavioral interview Tuesday. Build me 5 STAR stories from my wins log." → wins-curate (interview-stories mode) picks story-shaped wins with real conflict, drafts 90-second answers, and flags likely follow-ups.
• "We're opening a Staff Eng req — design the loop and the rubric." → hiring-craft walks signals → slot mapping → rubric with behavioral anchors → debrief discipline.
• "I have a report who's been underperforming for three months and I've been avoiding it." → performance-management diagnoses the stage (coachable gap vs. PIP-territory), structures the conversation, and walks through the documentation discipline.
• "Help me coach Priya through whether to take the staff role — without telling her what to do." → coaching-mode flips into ask-not-tell, applies GROW, and pushes back when the user catches themselves prescribing.
• "Build me a 12-month growth plan for Draymond." → report-career-architect reads the stakeholder-reflect file and produces a sequenced plan with manager moves, risks, and observable success criteria.
• "Promo cycle — draft the case for Michelle." → report-promo-case produces a panel-ready packet with cited evidence, calibrated solo-vs-shared credit, and gaps surfaced as pre-submission targets.
• "Before my skip-level update, give me a structured read on team health." → team-diagnosis produces a green/yellow/red across eight dimensions with cited evidence and top-3 risks worth acting on.
• "My team submitted an RFC for a new event-streaming layer — give me a senior-engineer read before I approve." → the-rfc-reviewer walks the doc through problem clarity, alternatives, trade-offs, failure modes, observability, and security with severity-ranked findings.
• "That meeting ended with everyone nodding but I don't trust it. Help me read it." → read-the-room interprets subtext (who held back, where consensus is performative, what positions are masking what interests) and produces hypotheses to verify directly — never claims as fact.
• "I need to drive an architecture change owned by the platform team without going to their VP. How?" → influence-without-authority diagnoses positions vs. interests, suggests sequencing the coalition (early believers first, decider last), and stays opinionated about the legitimacy line between influence and manipulation.
• "I'm running a multi-team program with a Q3 launch — map dependencies, design the gates, and draft the escalation if Platform slips." → the-program-manager produces the dependency map, gates per phase with explicit criteria, and escalation framing pre-loaded with a recommendation.
• "Set up my profile so I stop re-explaining who I am every session." → user-profile interviews you for role / level / strategic focus / communication style, drafts the anchor file, and other skills (spec writer, translator, explainer, promo case, career architect, metrics design, coaching, feedback) start reading it automatically.
• "Sunday evening — anything notable across all my reflections this week?" → patterns-watch scans stakeholder + wins + self files, surfaces unsolicited patterns (attention gaps, contradictions between stated focus and actual logged work, trajectory shifts) with citations to specific dated entries.
• "Draft a strategy doc for the platform area I just took over." → strategy-doc interviews you on target problem, approach, personas, SMART metrics, multi-month tracks, and (load-bearing) what you're explicitly not working on. Lives at ~/bettersense-work-reflections/strategy/platform.md and starts being read by spec writer / prioritization / metrics-design / pulse skills.
• "Run my Monday product pulse." → product-pulse queries connected MCPs (PostHog, Datadog, Stripe), produces a one-page dated report with usage metrics, counter-metrics, AI-specific signals (hallucination/refusal/eval drift), and ≤3 follow-up investigations. Saves to the pulses folder for that area.
• "Before my exec readout, what's the trajectory across the last 8 weeks of pulses?" → pulse-synthesize reads the folder and surfaces trends, anomalies, regime shifts — with citations to specific dated pulses. Refuses to forecast; calls out coverage gaps.
• "I need to brief the CEO on why our accuracy regressed." → the-translator reframes the numbers.
• "Help me cut this 30-item backlog to what we can ship this quarter." → prioritization-frameworks skill picks the right method and pressure-tests scoring assumptions.
• "Document why we picked Sonnet over Opus for this feature." → decision-log skill captures it in a format that survives the next model migration.
• "I have a hard 1:1 with a struggling engineer tomorrow." → one-on-one-prep builds the agenda; feedback-frameworks drafts the conversation.
• "My senior engineer keeps shutting down juniors in standup." → leadership-os (the Mirror mode) gives you the conversation script.

Stakeholder reflection: a worked example

The four stakeholder-* skills and self-reflect are a tighter system than the rest of the bundle — they share private data at ~/bettersense-work-reflections/ (configurable via $BETTERSENSE_WORK_REFLECTIONS_HOME) and are designed to be used together over months.

A note on origins

This was originally a feature inside the Voohy app — the same idea: register your stakeholders by category, answer cadence-driven reflection questions, accumulate insight over time. The Claude Code version is a deliberate revamp, and on balance it works better in this shape than as in-app screens, because the reflection sessions can lean on the rest of the skills bundle. A reflection naturally hands off to feedback-frameworks when feedback emerges, to one-on-one-prep when a 1:1 is coming up, to decision-log when a relationship-shaping decision gets made. None of those compositions were possible inside an app's bounded UX. The honest tradeoff: a CLI/IDE tool has more friction than a mobile app, so expect weekly or bi-weekly use, not daily.

File layout

~/bettersense-work-reflections/             # private, gitignored, on your local machine only
├── stakeholders.json
├── managing-up/
│   └── john-adams.md
├── managing-across/
│   ├── jill-smith.md
│   └── trae-green.md
├── managing-down/
│   ├── draymond-young.md
│   └── michelle-chang.md
├── teams/
│   └── client-delivery-abc.md
└── self/
    └── reflections.md

A typical lifecycle

1. Register. "I just got a new VP. Add John Adams to managing-up." → stakeholder-register creates ~/bettersense-work-reflections/managing-up/john-adams.md with frontmatter and waits to confirm before writing.
2. Reflect, weekly-ish. "Let me reflect on John." → stakeholder-reflect loads the file, picks 2–3 questions appropriate to the moment (cadence-aware, balancing ask and sense lenses), surfaces the prompt's things_to_consider, and walks through a real conversation. Pushes back on one-line answers and identity-level labels. Writes a dated entry per question.
3. Stay current. "What's due this week?" → stakeholder-due lists the overdue question × stakeholder pairs sorted by due_ratio (days_since / cadence). Or run it once via /schedule "Every Monday at 9am, run /stakeholder-due" to get a Monday-morning surfacing.
4. Synthesize, periodically. "Before John's quarterly skip-level, what do I know?" → stakeholder-synthesize reads the file, produces patterns / contradictions / blind spots / suggested next conversations, with every claim cited to specific dated entries. Hands off to feedback-frameworks or one-on-one-prep when a natural next step appears.
5. Self. Same shape, aimed at you. self-reflect covers behavior under pressure, communication, time/energy, fulfillment, advocating for yourself.
6. Maintain. "Jill is my manager now" / "Draymond left for Stripe" / "list my stakeholders" → stakeholder-manage handles the lifecycle: re-categorize across folders (history preserved), archive when someone leaves (file kept for retrospection), edit roles, list, rename. Defaults toward archive over delete.

Things to know before adopting

• The data lives outside the public repo. user-profile creates ~/bettersense-work-reflections/ on first run, gitignores it, and shows you a one-time privacy notice. The folder holds candid notes about real people — don't put it in Dropbox if you wouldn't put your journal there. Override the path with $BETTERSENSE_WORK_REFLECTIONS_HOME if you want it on an encrypted volume or somewhere else.
• Quality of synthesis depends on quality of input. One-line entries produce shallow synthesis. The things_to_consider field is surfaced prominently to help — use it.
• Synthesis is honest about its evidence. stakeholder-synthesize will not claim a pattern without citing dated entries. If your file is sparse, the synthesis will be tentative; if it's rich, the synthesis will be sharp.

Wins log: a worked example

The three wins-* skills are a parallel system to the stakeholder bundle — same data root, same shape, but the subject is you. They cover the "hype doc" / "brag document" / "win log" pattern: capture wins as they happen so you can remix them into a promo packet, behavioral interview answers, perf-review self-eval, or salary case when the moment comes.

A note on origins

This was originally a "Wins at Work" feature inside the Voohy app, since sunsetted. The Claude Code rebuild gains the same composition advantage as the stakeholder bundle: a wins entry can hand off to decision-log when it captures a judgment, to feedback-frameworks when it came from feedback work, to stakeholder-reflect when it was driven by a relationship. And wins-curate can compose with stakeholder-synthesize and self-reflect for a perf-review self-eval that draws from all three sources at once.

File layout

~/bettersense-work-reflections/
├── stakeholders.json
├── managing-up/...
├── managing-across/...
├── managing-down/...
├── teams/...
├── self/reflections.md
└── wins.md                          # newest entry on top

A typical lifecycle

1. Capture. "I just shipped contract-summarization to GA. Log it." → wins-log walks through the structured capture: type tags, scope, collaborators, honest credit framing, situation, action, quantified impact, evidence. Pushes back hard on vague impact and inflated solo claims.
2. Friday nudge. Wired via /schedule "Every Friday at 4pm, run /wins-due". Each Friday, wins-due checks the file and probes by category — judgment, recovery, mentorship, range — because "anything notable this week?" gets blank stares while "did you say a useful no?" gets memory hits. Accepts "honestly, nothing notable" without manufacturing wins.
3. Curate when it matters. "I have a promo case in two weeks." → wins-curate in promo-packet mode reads the log, maps wins to the dimensions a panel cares about (scope, impact, judgment, leadership, growth), produces a citation-backed packet, and surfaces gaps as prep targets ("judgment is thin in your log — strongest available is X, but a panel may want more"). For interviews, interview-stories mode picks story-shaped wins (recovery, judgment, range) and drafts 90-second STAR answers with anticipated follow-ups.

Things to know before adopting

• The "log it later" decay is real. Friday nudges help but won't fully prevent it. The wins captured weeks after the fact are usually thinner than wins captured in-week.
• *The skill defaults to probing, not cheerleading.* Self-promotion friction varies a lot by user — wins-log is calibrated for users who tend to undercount. If it pushes too hard for you, say so and it'll dial back.
• Calibration is non-negotiable for external artifacts. A promo packet that overclaims solo credit on team work hurts the case more than a thinner-but-honest one. The curate skill enforces this.
• Composes naturally with perf-review prep. wins-curate (perf-review) reads wins.md plus self-reflect's growth language plus stakeholder-synthesize's relationship signals — the three together produce a self-eval that has both delivery breadth and relational depth.

For engineering managers: the management-craft bundle

Seven skills (hiring-craft, performance-management, coaching-mode, report-career-architect, report-promo-case, team-diagnosis, engineering-health) and one agent (the-rfc-reviewer) form a tighter system aimed at the highest-stakes work an engineering manager does — the work most managers do loosely because nobody handed them a forcing function for it.

These compose with the rest of the bundle but earn their keep on their o