Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

feat: add /humanize and /weekly commands (v3.2)

Brenno Ferrariaa067975eb76
diff --git a/.claude/commands/humanize.md b/.claude/commands/humanize.md
new file mode 100644
index 0000000..0b9123f
--- /dev/null
+++ b/.claude/commands/humanize.md
@@ -0,0 +1,82 @@
+---
+description: "Voice-calibrated editing — makes Claude-drafted text sound like you wrote it, not like AI wrote it."
+---
+
+Edit a note to match your writing voice. This is voice calibration, not pattern removal — learn HOW you write, not just what to avoid.
+
+## Usage
+
+```
+/humanize <file path or note name>
+```
+
+## Workflow
+
+### 1. Load Voice Samples
+
+Read 2-3 recent notes you actually wrote or heavily edited to calibrate voice:
+- `brain/North Star.md` — how you write about yourself
+- The most recent `work/1-1/*.md` note — natural conversational voice
+- Any brain note with your authentic writing style
+
+Extract voice fingerprint: sentence length, punctuation habits, how you open sections, how you qualify statements, ratio of direct-to-hedged language, use of dashes and fragments.
+
+### 2. Read Target Note
+
+Read the note specified in $ARGUMENTS (resolve as wikilink name or file path).
+
+Detect context from frontmatter and folder:
+- **`work/1-1/`** → conversational, direct, uses "I", okay to be informal
+- **`perf/` review content** → corporate-confident but human, evidence-based, respect charcount
+- **`work/incidents/`** → precise, factual, timeline-oriented, no filler
+- **`brain/`** → terse shorthand, fragments okay
+- **Default** → colleague-to-colleague, like explaining something in a 1:1
+
+### 3. Edit In-Place
+
+Rewrite the note's content to match your voice. Key principles:
+
+**Voice rules (from samples):**
+- Direct statements, not hedged ones ("This was stressful" not "This presented some challenges")
+- Match your natural rhythm — fragments, dashes, whatever you actually use
+- Observations should be sharp, not softened
+- A concise 600-char section is better than a padded 950-char one
+
+**Anti-patterns (kill these):**
+- "Notably", "significantly", "demonstrates", "leveraged", "facilitated"
+- "It's worth noting that..." — just note it
+- "This showcases..." — just describe what happened
+- Hedge stacking: "potentially", "arguably", "it could be said that"
+- Empty transitions: "Moving forward", "In terms of", "With regard to"
+- Passive voice where active is natural: "was identified" → "found"
+- Bullet points that all start with the same word pattern
+- Rhetorical questions followed by immediate answers
+
+**Preserve untouched:**
+- All YAML frontmatter (pass through unchanged)
+- `[[wikilinks]]` and `[[link|aliases]]`
+- `![[embeds]]`
+- Callout blocks (`> [!type]`)
+- Block IDs (`^block-id`)
+- Code blocks
+- Tables (content can be edited, structure preserved)
+- Checkboxes and task items
+
+### 4. Summarize Changes
+
+Present a brief summary (NOT a full diff):
+- **Tone shift**: what changed overall (e.g., "removed hedging, shortened sentences")
+- **Key rewrites**: 2-3 examples of before/after for the most significant changes
+- **Preserved**: confirm what was left untouched and why
+
+Don't show unchanged sections. The user can run `git diff` for the full picture.
+
+## Important
+
+- This is NOT "remove AI words from a list." It's "make this sound like the same person who wrote the other notes in this vault."
+- If the note is already well-written, say so and make minimal changes. Don't edit for the sake of editing.
+- Respect the context — a peer review needs to stay professional even after humanizing. A 1:1 note can be loose.
+- If charcount matters (review content in `perf/`), verify limits after editing with `.claude/scripts/charcount.sh`.
+
+Content to edit:
+$ARGUMENTS
diff --git a/.claude/commands/weekly.md b/.claude/commands/weekly.md
new file mode 100644
index 0000000..ed02a4f
--- /dev/null
+++ b/.claude/commands/weekly.md
@@ -0,0 +1,87 @@
+---
+description: "Weekly synthesis — cross-session review of vault activity, North Star alignment, patterns, uncaptured wins, and forward priorities."
+---
+
+Cross-session synthesis of the past week. Bridges daily standup (lightweight) and quarterly review brief (comprehensive). This is ANALYSIS, not verification — find patterns, surface drift, detect uncaptured work.
+
+## Subagent
+
+- **`brag-spotter`** — run with weekly scope to find uncaptured wins and competency gaps
+
+## Workflow
+
+### 1. Gather Week's Activity
+
+Automated — no user input needed:
+
+- `git log --since="7 days ago" --oneline --no-merges` — all vault changes
+- List all notes modified in the past 7 days (git + filesystem)
+- Read any `work/1-1/*.md` notes from this week
+- Check `work/active/` for status changes
+- Check `work/incidents/` for new or updated incidents
+- Read today's and recent daily notes if they exist: `obsidian daily:read`
+
+### 2. North Star Alignment
+
+Read `brain/North Star.md` and compare actual activity against stated focus:
+
+- **Aligned work**: which Current Focus items got attention this week?
+- **Drift**: work that doesn't map to any stated goal (not necessarily bad — flag it)
+- **Silent goals**: focus items with zero commits, zero note updates, zero mentions
+- **Emerging themes**: work patterns suggesting a focus shift that hasn't been written down yet
+
+### 3. Cross-Day Patterns
+
+Look across the week's notes for:
+- Recurring themes (same topic in multiple notes or days)
+- Multiple incidents or issues touching the same system
+- Topics appearing in BOTH work notes and 1:1s (these are signals)
+- Context that evolved across sessions (decisions that shifted, understanding that deepened)
+
+### 4. Uncaptured Win Detection
+
+Run the `brag-spotter` subagent scoped to the past 7 days.
+
+Additionally check:
+- Were completed items logged in `perf/Brag Doc.md` or the current quarter's brag note?
+- Any 1:1 feedback or kudos not captured?
+- Incident contributions not bragged about?
+
+### 5. Competency Signal Mapping
+
+For each competency in `perf/competencies/`:
+- Was it exercised this week? (check work note links, incident roles, 1:1 topics)
+- If yes, is there a backlink from the evidence to the competency note?
+
+Present as a compact table: competency name, exercised (yes/no), linked (yes/no).
+
+### 6. Forward Look
+
+- Blocked items or upcoming deadlines from active work notes
+- North Star goals that need attention next week
+- Scheduled 1:1s or meetings worth preparing for
+- Suggested priority ordering for next week based on goals + momentum + gaps
+
+### 7. Present Synthesis
+
+Structure the output as:
+
+- **This Week**: 3-5 bullet summary of what actually happened
+- **North Star Check**: alignment status — what's on track, what drifted, what's silent
+- **Patterns**: cross-day themes worth noting
+- **Uncaptured Wins**: anything that should be in the brag doc (from brag-spotter)
+- **Competency Coverage**: compact table
+- **Next Week**: suggested priorities and attention areas
+
+After presenting, offer:
+- "Want me to add any of these wins to the brag doc?"
+- "Should I update North Star with any focus shifts?"
+- "Want me to save this as `thinking/weekly-YYYY-MM-DD.md`?"
+
+## Important
+
+- This is transient analysis by default — do NOT create a file unless the user asks.
+- Keep the tone analytical, not cheerful. This is a status check, not a celebration.
+- Be honest about drift and silent goals — the value is in surfacing what's NOT happening, not just what is.
+- Don't duplicate standup (daily, what's next) or wrap-up (session, verify quality). This is SYNTHESIS across days.
+- If it was a light week (few commits, no new notes), say so. Don't pad the analysis.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 048400e..9b259cb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,16 @@
# Changelog
+## v3.2 — 2026-03-29
+
+### Added
+- `/humanize` command — voice-calibrated editing that matches your writing style, not a generic AI word blacklist
+- `/weekly` command — cross-session weekly synthesis with North Star alignment, pattern detection, and uncaptured win spotting
+
+### Changed
+- CLAUDE.md: reordered command table by category, added new commands, fixed stale counts (10→14 commands, 7→8 agents), added `review-fact-checker` subagent
+- README: updated command table, daily workflow section, command and agent counts
+- `brain/Skills.md`: added Editing & Synthesis category, new commands, usage notes, and Weekly Review workflow
+
## v3.1 — 2026-03-27
### Added
diff --git a/CLAUDE.md b/CLAUDE.md
index 999b634..f7a3aea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,18 +19,20 @@ Defined in `.claude/commands/`. See [[Skills]] for full documentation.
| Command | Purpose |
|---------|---------|
-| `/peer-scan` | Deep scan a peer's GitHub PRs for review prep |
-| `/slack-scan` | Deep scan Slack channels/DMs for evidence |
+| `/standup` | Morning kickoff -- load context, review yesterday, surface tasks, priorities |
+| `/dump` | Freeform capture -- dump anything, gets routed to the right notes |
+| `/wrap-up` | Full session review -- verify notes, indexes, links, suggest improvements |
+| `/humanize` | Voice-calibrated editing -- make notes sound like you, not AI |
+| `/weekly` | Weekly synthesis -- cross-session patterns, North Star alignment, uncaptured wins |
| `/capture-1on1` | Capture 1:1 meeting transcript into structured vault note |
-| `/vault-audit` | Audit indexes, links, orphans, stale context |
-| `/review-brief` | Generate review brief (manager or peer version) |
| `/incident-capture` | Capture incident from Slack channels/DMs into structured vault notes |
-| `/project-archive` | Move completed project from active/ to archive/, update indexes |
-| `/wrap-up` | Full session review -- verify notes, indexes, links, suggest improvements |
-| `/dump` | Freeform capture -- dump anything, gets routed to the right notes |
-| `/standup` | Morning kickoff -- load context, review yesterday, surface tasks, priorities |
+| `/slack-scan` | Deep scan Slack channels/DMs for evidence |
+| `/peer-scan` | Deep scan a peer's GitHub PRs for review prep |
+| `/review-brief` | Generate review brief (manager or peer version) |
| `/self-review` | Write self-assessment for review tool -- projects, competencies, principles |
| `/review-peer` | Write peer review -- projects, principles, performance summary |
+| `/vault-audit` | Audit indexes, links, orphans, stale context |
+| `/project-archive` | Move completed project from active/ to archive/, update indexes |
## Vault Structure
@@ -55,8 +57,8 @@ Defined in `.claude/commands/`. See [[Skills]] for full documentation.
| `reference/` | Codebase knowledge, architecture maps | Flow docs, architecture docs |
| `thinking/` | Scratchpad for drafts and reasoning | Named `YYYY-MM-DD-topic.md` |
| `templates/` | Obsidian templates | `Work Note.md`, `Decision Record.md`, etc. |
-| `.claude/commands/` | 10 slash commands | See command table above |
-| `.claude/agents/` | 7 subagents | See subagents table below |
+| `.claude/commands/` | 14 slash commands | See command table above |
+| `.claude/agents/` | 8 subagents | See subagents table below |
| `.claude/scripts/` | Hook scripts | `session-start.sh`, `classify-message.py`, `validate-write.py`, `pre-compact.sh` |
| `.claude/skills/` | Obsidian + QMD skills | Loaded automatically via Skill tool |
@@ -298,13 +300,14 @@ Specialized agents in `.claude/agents/` for heavy operations. They run in isolat
| Agent | Purpose | Invoked by |
|-------|---------|------------|
-| `brag-spotter` | Finds uncaptured wins and competency gaps | `/wrap-up` |
+| `brag-spotter` | Finds uncaptured wins and competency gaps | `/wrap-up`, `/weekly` |
| `context-loader` | Loads all vault context about a person, project, or concept | Direct |
| `cross-linker` | Finds missing wikilinks, orphans, broken backlinks | `/vault-audit` |
| `people-profiler` | Bulk creates/updates person notes from Slack profiles | `/incident-capture` |
| `review-prep` | Aggregates all performance evidence for a review period | `/review-brief` |
| `slack-archaeologist` | Full Slack reconstruction -- every message, thread, profile | `/incident-capture` |
| `vault-librarian` | Deep vault maintenance -- orphans, broken links, stale notes | `/vault-audit` |
+| `review-fact-checker` | Verifies every claim in a review draft against vault sources | `/self-review`, `/review-peer` |
## Hooks
diff --git a/README.md b/README.md
index 05382d9..f00baa6 100644
--- a/README.md
+++ b/README.md
@@ -109,7 +109,7 @@ Five lifecycle hooks handle routing automatically:
**End of day**: Say "wrap up" and Claude invokes `/wrap-up` — verifies notes, updates indexes, checks links, spots uncaptured wins.
-**Weekly**: Run `/vault-audit` to catch orphan notes, broken links, and stale content.
+**Weekly**: Run `/weekly` for cross-session synthesis — North Star alignment, patterns, uncaptured wins, and next-week priorities. Run `/vault-audit` to catch orphan notes, broken links, and stale content.
**Review season**: Run `/review-brief manager` and get a structured review prep document with all the evidence already linked.
@@ -124,15 +124,17 @@ Defined in `.claude/commands/`. Run them in any Claude Code session.
| `/standup` | Morning kickoff — loads context, reviews yesterday, surfaces tasks, suggests priorities |
| `/dump` | Freeform capture — talk naturally about anything, Claude routes it all to the right notes |
| `/wrap-up` | Full session review — verify notes, indexes, links, suggest improvements |
+| `/humanize` | Voice-calibrated editing — makes Claude-drafted text sound like you wrote it |
+| `/weekly` | Weekly synthesis — cross-session patterns, North Star alignment, uncaptured wins |
| `/capture-1on1` | Capture a 1:1 meeting transcript into a structured vault note |
| `/incident-capture` | Capture an incident from Slack/channels into structured notes |
| `/slack-scan` | Deep scan Slack channels/DMs for evidence |
| `/peer-scan` | Deep scan a peer's GitHub PRs for review prep |
| `/review-brief` | Generate a review brief (manager or peer version) |
-| `/vault-audit` | Audit indexes, links, orphans, stale context |
-| `/project-archive` | Move a completed project from active/ to archive/, update indexes |
| `/self-review` | Write your self-assessment for review season — projects, competencies, principles |
| `/review-peer` | Write a peer review — projects, principles, performance summary |
+| `/vault-audit` | Audit indexes, links, orphans, stale context |
+| `/project-archive` | Move a completed project from active/ to archive/, update indexes |
---
@@ -142,7 +144,7 @@ Specialized agents that run in isolated context windows. They handle heavy opera
| Agent | Purpose | Invoked by |
|-------|---------|------------|
-| `brag-spotter` | Finds uncaptured wins and competency gaps | `/wrap-up` |
+| `brag-spotter` | Finds uncaptured wins and competency gaps | `/wrap-up`, `/weekly` |
| `context-loader` | Loads all vault context about a person, project, or concept | Direct |
| `cross-linker` | Finds missing wikilinks, orphans, broken backlinks | `/vault-audit` |
| `people-profiler` | Bulk creates/updates person notes from Slack profiles | `/incident-capture` |
@@ -253,7 +255,7 @@ thinking/ Scratchpad for drafts — promote findings, then delete
templates/ Obsidian templates with YAML frontmatter
.claude/
- commands/ 12 slash commands
+ commands/ 14 slash commands
agents/ 8 subagents
scripts/ Hook scripts + charcount.sh utility
skills/ Obsidian + QMD skills
diff --git a/brain/Skills.md b/brain/Skills.md
index 3c2da1d..49fa1b1 100644
--- a/brain/Skills.md
+++ b/brain/Skills.md
@@ -19,6 +19,13 @@ Custom slash commands, subagents, and reusable workflows. Defined in `.claude/co
| `/dump` | Freeform capture — dump anything, gets routed to the right notes automatically |
| `/wrap-up` | Full session review — verify notes, indexes, links, suggest improvements. Auto-triggered on "wrap up". |
+### Editing & Synthesis
+
+| Command | Purpose |
+|---------|---------|
+| `/humanize` | Voice-calibrated editing — makes Claude-drafted text sound like you wrote it |
+| `/weekly` | Weekly synthesis — cross-session patterns, North Star alignment, uncaptured wins |
+
### Capture & Documentation
| Command | Purpose |
@@ -43,11 +50,35 @@ Custom slash commands, subagents, and reusable workflows. Defined in `.claude/co
| `/vault-audit` | Deep structural audit — indexes, frontmatter, links, Bases, folder placement, stale context |
| `/project-archive` | Move completed project from `work/active/` to `work/archive/YYYY/`, update all indexes |
+## Usage Notes
+
+**Daily:**
+- `/standup` replaces the manual session start — reads North Star, active work, tasks, git log
+- `/dump` processes freeform text and routes each piece to the correct note type and folder
+- `/wrap-up` is auto-triggered when you say "wrap up" — runs full session review
+
+**Editing & Synthesis:**
+- `/humanize` calibrates against your actual writing samples, not a word blacklist. Detects context from frontmatter (review → corporate-confident, incident → precise, 1:1 → conversational). Run after drafting any note to make it sound human.
+- `/weekly` bridges standup and review brief — run at end of week for cross-session patterns, North Star drift, and uncaptured wins. Output is transient by default; offer to promote findings to brag doc or North Star.
+
+**Capture:**
+- `/capture-1on1` handles transcripts, raw notes, or summaries
+- `/incident-capture` takes Slack URLs and produces structured incident documentation
+- `/slack-scan` should be run AFTER `/peer-scan` to add context beyond code (leadership, communication, collaboration evidence)
+
+**Performance:**
+- `/peer-scan` works best when launched as parallel agents (one per person)
+- `/review-brief` needs the private brief to exist first — it generates filtered versions from it
+
+**Maintenance:**
+- `/vault-audit` should be run at the end of substantial sessions — catches stale indexes and mixed context
+- `/project-archive` handles the active/ → archive/ move with index updates
+
## Subagents
| Agent | Purpose | Invoked by |
|-------|---------|------------|
-| `brag-spotter` | Proactively finds uncaptured wins and competency gaps | `/wrap-up` |
+| `brag-spotter` | Proactively finds uncaptured wins and competency gaps | `/wrap-up`, `/weekly` |
| `context-loader` | Loads all vault context about a person, project, incident, or concept | Direct — "load context on X" |
| `cross-linker` | Finds missing wikilinks, orphans, broken backlinks across the vault | `/vault-audit` |
| `people-profiler` | Bulk create/update person notes from Slack profiles | `/incident-capture` |
@@ -79,6 +110,13 @@ If QMD is installed (`npm install -g @tobilu/qmd`), the vault has semantic searc
SessionStart hook runs `qmd update` automatically. See `.claude/skills/qmd/SKILL.md` for full reference.
+## Workflow: Weekly Review
+
+1. **`/weekly`** — synthesize the week's activity, check alignment, find patterns
+2. Promote any uncaptured wins to brag doc
+3. Update North Star if focus shifted
+4. **`/wrap-up`** — close the session cleanly
+
## Workflow: Full Review Cycle Prep
1. **`/review-brief manager`** — generate the manager context transfer doc