@forwardimpact/basecamp 2.0.0 → 2.2.0

package/template/.claude/skills/track-candidates/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: track-candidates
+description: Scan synced email threads for recruitment candidates, extract structured profiles, and create/update notes in knowledge/Candidates/. Use when the user asks to track candidates, process recruitment emails, or update the hiring pipeline.
+---
+
+# Track Candidates
+
+Scan synced email threads from `~/.cache/fit/basecamp/apple_mail/` for
+recruitment candidates. Extract structured candidate profiles and create/update
+notes in `knowledge/Candidates/`. This builds a local, searchable recruitment
+pipeline from scattered email threads.
+
+## Trigger
+
+Run this skill:
+
+- When the user asks to track, process, or update candidates
+- When the user asks about recruitment pipeline status
+- After `sync-apple-mail` has pulled new threads
+
+## Prerequisites
+
+- Synced email data in `~/.cache/fit/basecamp/apple_mail/` (from
+  `sync-apple-mail`)
+- User identity configured in `USER.md`
+
+## Inputs
+
+- `~/.cache/fit/basecamp/apple_mail/*.md` — synced email threads
+- `~/.cache/fit/basecamp/apple_mail/attachments/` — CV/resume attachments
+- `~/.cache/fit/basecamp/state/graph_processed` — tracks processed files (shared
+  with `extract-entities`)
+- `USER.md` — user identity for self-exclusion
+
+## Outputs
+
+- `knowledge/Candidates/{Full Name}/brief.md` — candidate profile note
+- `knowledge/Candidates/{Full Name}/CV.pdf` — local copy of CV (or `CV.docx`)
+- `~/.cache/fit/basecamp/state/graph_processed` — updated with processed threads
+
+---
+
+## Before Starting
+
+1. Read `USER.md` to get the user's name, email, and domain.
+2. Find new/changed email files to process:
+
+```bash
+node .claude/skills/extract-entities/scripts/state.mjs check
+```
+
+This outputs one file path per line for all source files that are new or
+changed. Filter this list to only `apple_mail/*.md` files — calendar events are
+not relevant for candidate tracking.
+
+**Process in batches of 10 files per run.**
+
+## Step 0: Build Candidate Index
+
+Scan existing candidate notes to avoid duplicates:
+
+```bash
+ls -d knowledge/Candidates/*/
+```
+
+Each candidate has their own directory at `knowledge/Candidates/{Name}/`
+containing standardized files:
+
+- `brief.md` — the candidate profile note
+- `CV.pdf` (or `CV.docx`) — local copy of CV (if available)
+
+For each existing note, read the header fields (Name, Role, Source, Status) to
+build a mental index of known candidates.
+
+Also scan `knowledge/People/`, `knowledge/Organizations/`, and
+`knowledge/Projects/` to resolve recruiter names, agency orgs, and project
+links.
+
+## Step 1: Identify Recruitment Emails
+
+For each new/changed email thread, determine if it contains candidate
+information. Look for these signals:
+
+### CV/Resume Attachments
+
+Check `~/.cache/fit/basecamp/apple_mail/attachments/{thread_id}/` for PDF or
+DOCX files with candidate names in filenames.
+
+### Recruiter Sender Domains
+
+Emails from known recruitment agency domains. Map sender domains to
+organizations using `knowledge/Organizations/` — look for notes tagged as
+recruitment agencies.
+
+If no known agencies exist yet, use sender patterns as hints:
+
+- Multiple candidates presented by the same sender
+- Structured profile formatting (rate, availability, skills)
+- Forwarding candidate CVs on behalf of others
+
+### Profile Presentation Patterns
+
+Look for structured candidate descriptions containing:
+
+- "Rate:" or rate/cost information
+- "Availability:" or notice period
+- "English:" or language level
+- "Location:" or country/city
+- Candidate name + role formatting (e.g. "Staff Software Engineer")
+- "years of experience" or "YoE"
+- Skills/tech stack listings
+
+### Interview Scheduling
+
+- "schedule a call", "schedule an interview"
+- "first interview", "second interview", "technical interview"
+- "interview slot", "available for a call"
+
+### Follow-up on Existing Candidates
+
+Threads that mention a candidate already in `knowledge/Candidates/` by name —
+these update pipeline status.
+
+**Skip threads that don't match any signal.** Not all email threads are
+recruitment-related.
+
+## Step 2: Extract Candidate Data
+
+For each candidate found in a recruitment email, extract:
+
+| Field             | Source                                            | Required            |
+| ----------------- | ------------------------------------------------- | ------------------- |
+| **Name**          | Filename, email body, CV                          | Yes                 |
+| **Role**          | Email body, CV                                    | Yes                 |
+| **Rate**          | Email body (e.g. "$120/hr", "€80/h")              | If available        |
+| **Availability**  | Email body (e.g. "1 month notice", "immediately") | If available        |
+| **English**       | Email body (e.g. "B2", "Upper-intermediate")      | If available        |
+| **Location**      | Email body, CV                                    | If available        |
+| **Source agency** | Sender domain → Organization                      | Yes                 |
+| **Recruiter**     | Email sender or CC'd recruiter                    | Yes                 |
+| **CV path**       | Attachment directory                              | If available        |
+| **Skills**        | Email body, CV                                    | If available        |
+| **Gender**        | Name, pronouns, recruiter context                 | If identifiable     |
+| **Summary**       | Email body, CV                                    | Yes — 2-3 sentences |
+
+### Determining Gender
+
+Record the candidate's gender when identifiable from the email or CV:
+
+- Pronouns used by the recruiter ("she is available", "her CV attached")
+- Gendered titles ("Ms.", "Mrs.", "Mr.")
+- First name when culturally unambiguous
+
+Record as `Woman`, `Man`, or `—` (unknown). When uncertain, use `—` — never
+guess. This field supports pool diversity tracking; it has **no bearing** on
+hiring decisions or assessment criteria.
+
+### Determining Source and Recruiter
+
+- Map sender email domain to an organization in `knowledge/Organizations/`.
+- The person who sent or forwarded the candidate profile is the recruiter. Look
+  them up in `knowledge/People/` and link with `[[People/Name]]`.
+- If the organization or recruiter doesn't exist yet, create notes for them.
+
+### CV Attachment Path
+
+Check for attachments:
+
+```bash
+ls ~/.cache/fit/basecamp/apple_mail/attachments/{thread_id}/
+```
+
+Match CV files to candidates by name similarity in the filename. Copy the CV
+into the candidate's directory with a standardized name:
+
+```bash
+mkdir -p "knowledge/Candidates/{Full Name}"
+cp "~/.cache/fit/basecamp/apple_mail/attachments/{thread_id}/{filename}" \
+   "knowledge/Candidates/{Full Name}/CV.pdf"
+```
+
+Use `CV.pdf` for PDF files and `CV.docx` for Word documents. The `## CV` link in
+the brief uses a relative path: `./CV.pdf`.
+
+## Step 3: Determine Pipeline Status
+
+Assign a status based on the email context:
+
+| Status             | Signal                                                |
+| ------------------ | ----------------------------------------------------- |
+| `new`              | CV/profile received, no response yet                  |
+| `screening`        | Under review, questions asked about the candidate     |
+| `first-interview`  | First interview scheduled or completed                |
+| `second-interview` | Second interview scheduled or completed               |
+| `offer`            | Offer extended                                        |
+| `hired`            | Accepted and onboarding                               |
+| `rejected`         | Explicitly passed on ("not a fit", "pass", "decline") |
+| `on-hold`          | Paused, waiting on notice period, or deferred         |
+
+**Default to `new`** if no response signals are found. Read the full thread
+chronologically to determine the most recent status.
+
+### Status Advancement Signals
+
+Look for these patterns in the hiring manager's replies:
+
+- "let's schedule" / "set up an interview" → `first-interview`
+- "second round" / "follow-up interview" → `second-interview`
+- "not what we're looking for" / "pass" → `rejected`
+- "extend an offer" / "make an offer" → `offer`
+- "they've accepted" / "start date" → `hired`
+- "put on hold" / "come back to later" → `on-hold`
+- No response to profile → remains `new`
+
+## Step 4: Build Pipeline Timeline
+
+Extract a chronological timeline from the thread:
+
+```markdown
+## Pipeline
+- **2026-01-29**: Profile shared by {Recruiter} ({Agency})
+- **2026-02-03**: {Recruiter} followed up asking about scheduling
+- **2026-02-10**: {Hiring Manager} requested first interview
+```
+
+Each entry: `**{date}**: {what happened}` — one line per meaningful event.
+Include who did what. Skip noise (signature blocks, disclaimers, forwarded
+headers).
+
+## Step 5: Write Candidate Note
+
+### For NEW candidates
+
+Create the candidate directory and note:
+
+```bash
+mkdir -p "knowledge/Candidates/{Full Name}"
+```
+
+Then create `knowledge/Candidates/{Full Name}/brief.md`:
+
+```markdown
+# {Full Name}
+
+## Info
+**Role:** {role title}
+**Rate:** {rate or "—"}
+**Availability:** {availability or "—"}
+**English:** {level or "—"}
+**Location:** {location or "—"}
+**Gender:** {Woman / Man / —}
+**Source:** [[Organizations/{Agency}]] via [[People/{Recruiter Name}]]
+**Status:** {pipeline status}
+**First seen:** {date profile was shared, YYYY-MM-DD}
+**Last activity:** {date of most recent thread activity, YYYY-MM-DD}
+
+## Summary
+{2-3 sentences: role, experience level, key strengths}
+
+## CV
+- [CV.pdf](./CV.pdf)
+
+## Connected to
+- [[Organizations/{Agency}]] — sourced by
+- [[People/{Recruiter}]] — recruiter
+
+## Pipeline
+- **{date}**: {event}
+
+## Skills
+{comma-separated skill tags}
+
+## Notes
+```
+
+If a CV attachment exists, **copy it into the candidate directory** before
+writing the note.
+
+If no CV attachment exists, omit the `## CV` section entirely.
+
+### For EXISTING candidates
+
+Read `knowledge/Candidates/{Full Name}/brief.md`, then apply targeted edits:
+
+- Update **Status** if it has advanced
+- Update **Last activity** date
+- Add new **Pipeline** entries at the bottom (chronological order)
+- Update **Rate**, **Availability**, or other fields if new information is
+  available
+- Add new **Skills** if mentioned
+
+**Use precise edits — don't rewrite the entire file.**
+
+## Step 5b: Capture Key Insights
+
+After writing or updating candidate notes, check whether any **high-signal
+observations** belong in `knowledge/Candidates/Insights.md`. This is a shared
+file for cross-candidate strategic thinking.
+
+**Add an insight only when:**
+
+- A candidate may be better suited for a **different role** than the one they
+  applied for
+- A candidate stands out as a **strong match** for a specific team or leader
+- There's a meaningful **comparison between candidates** (e.g. complementary
+  strengths, overlapping profiles)
+- A hiring decision or trade-off needs to be **remembered across sessions**
+
+**Do NOT add:**
+
+- Per-candidate status updates (that's what `brief.md` is for)
+- Generic strengths/weaknesses already captured in interview notes
+- Anything that only matters within a single candidate's context
+
+Format: one bullet per insight under `## Placement Notes`, with
+`[[Candidates/Name/brief|Name]]` links and relevant people/org backlinks.
+
+## Step 6: Ensure Bidirectional Links
+
+After writing candidate notes, verify links go both ways:
+
+| If you add...            | Then also add...                            |
+| ------------------------ | ------------------------------------------- |
+| Candidate → Organization | Organization → Candidate                    |
+| Candidate → Recruiter    | Recruiter → Candidate (in Activity section) |
+| Candidate → Project      | Project → Candidate (in People section)     |
+
+Use absolute paths: `[[Candidates/Name/brief|Name]]`,
+`[[Organizations/Agency]]`, `[[People/Recruiter]]`.
+
+**Important:** Only add backlinks to Organization/People/Project notes if they
+don't already reference the candidate. Check before editing.
+
+## Step 7: Update Graph State
+
+After processing each email thread, mark it as processed:
+
+```bash
+node .claude/skills/extract-entities/scripts/state.mjs update "{file_path}"
+```
+
+This uses the same state file as `extract-entities`, so threads processed here
+won't be re-scanned by either skill (unless the file changes).
+
+## Step 8: Tag Skills with Framework IDs
+
+When a candidate's email or CV mentions technical skills, map them to the
+engineering framework using `fit-pathway`:
+
+```bash
+npx fit-pathway skill --list
+```
+
+Use framework skill IDs (e.g. `data_integration`, `full_stack_development`,
+`architecture_and_design`) in the **Skills** section of the candidate brief
+instead of free-form tags. This enables consistent cross-candidate comparison.
+
+If a candidate has a CV attachment, flag them for the `analyze-cv` skill which
+produces a full framework-aligned assessment.
+
+## Quality Checklist
+
+- [ ] Scanned all new/changed email threads for recruitment signals
+- [ ] Extracted all candidates found (check attachment directories too)
+- [ ] Each candidate has a complete note with all available fields
+- [ ] CV paths are correct and point to actual files
+- [ ] Pipeline status reflects the latest thread activity
+- [ ] Timeline entries are in chronological order
+- [ ] Used `[[absolute/path]]` links throughout
+- [ ] Bidirectional links are consistent
+- [ ] Graph state updated for all processed threads
+- [ ] No duplicate candidate notes created
+- [ ] Key strategic insights added to `Insights.md` where warranted
+- [ ] Skills tagged using framework skill IDs where possible
+- [ ] Gender field populated where identifiable (Woman / Man / —)

package/template/.claude/skills/weekly-update/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: weekly-update
+description: Generate or refresh a weekly priorities document. Pulls from task boards, recent activity, and calendar to create a point-in-time snapshot. Use when the user asks to update their weekly, prep for the week, or on a Monday morning schedule.
+---
+
+# Weekly Update
+
+Generate or refresh a weekly priorities document in
+`knowledge/Weeklies/{Person Name}/`. Each weekly is a point-in-time snapshot —
+created at the start of the week, updated as priorities shift, and closed out
+with a retrospective at end-of-week.
+
+## Trigger
+
+Run this skill:
+
+- When the user asks to update their weekly or prep for the week
+- Monday mornings (scheduled)
+- When the user asks to review someone's weekly
+- End-of-week to fill in accomplishments and retrospective
+
+## Prerequisites
+
+- `knowledge/Weeklies/` directory exists
+- `knowledge/Tasks/{Person Name}.md` exists (task board — see `manage-tasks`
+  skill)
+- Calendar data in `~/.cache/fit/basecamp/apple_calendar/`
+- User identity configured in `USER.md`
+
+## Inputs
+
+- `knowledge/Tasks/{Person Name}.md` — current task board
+- `knowledge/People/{Person Name}.md` — recent activity, context
+- `~/.cache/fit/basecamp/apple_calendar/*.json` — calendar events for the week
+- Previous weekly document (if exists) — for continuity and carry-forward
+
+## Outputs
+
+- `knowledge/Weeklies/{Person Name}/{YYYY}-W{WW}.md` — the weekly document
+
+---
+
+## Weekly Document Format
+
+```markdown
+# {YYYY}-W{WW} — {Person Name}
+
+> {Focus statement: one sentence summarizing the week's theme}
+
+## Priorities
+
+- [ ] Priority one — [[Projects/Name]]
+- [ ] Priority two
+- [x] Completed priority
+
+## Key Meetings
+
+- **Monday**: Meeting title with [[People/Name]] — purpose
+- **Wednesday**: Meeting title — purpose
+
+## Blockers
+
+- Waiting on X from [[People/Name]]
+
+## Accomplishments
+
+- Completed X
+- Shipped Y
+
+## Retrospective
+
+- **Went well:** ...
+- **Didn't go as planned:** ...
+- **Carry forward:** ...
+```
+
+**Key conventions:**
+
+- **Week numbers:** ISO 8601 (e.g., `2026-W08`)
+- **Priorities:** Top 3-7 items pulled from the task board
+- **Key Meetings:** Substantive meetings only (skip recurring standups)
+- **Retrospective:** Filled at end-of-week only
+- **All backlinks** use absolute paths: `[[People/Name]]`, `[[Projects/Name]]`,
+  `[[Tasks/Name]]`
+
+## Before Starting
+
+1. Read `USER.md` to identify the user.
+2. Determine the target person (default: current user from `USER.md`).
+3. Calculate the current ISO week number and date range:
+
+```bash
+# Current ISO week
+date +%G-W%V
+
+# Monday and Friday of current week (macOS)
+date -v-mon +%Y-%m-%d
+date -v+fri +%Y-%m-%d
+```
+
+4. Check if a weekly already exists for this week:
+
+```bash
+ls "knowledge/Weeklies/{Person Name}/" 2>/dev/null
+```
+
+5. Determine the mode:
+   - **No existing weekly:** Create new (start-of-week)
+   - **Existing weekly:** Update (mid-week or end-of-week)
+
+## Step 1: Gather Context
+
+### 1a. Read the task board
+
+```bash
+cat "knowledge/Tasks/{Person Name}.md"
+```
+
+Extract:
+
+- `## In Progress` tasks → top priorities (already being worked on)
+- `## Open` tasks with `high` priority or near due dates → candidate priorities
+- `## Blocked` tasks → blockers section
+- `## Recently Done` tasks completed this week → accomplishments
+
+### 1b. Read recent activity
+
+```bash
+cat "knowledge/People/{Person Name}.md"
+```
+
+Look at the `## Activity` section for entries from this week. These inform
+accomplishments and provide context for the focus statement.
+
+### 1c. Read calendar for the week
+
+Find events falling within the Monday–Friday range:
+
+```bash
+ls ~/.cache/fit/basecamp/apple_calendar/
+```
+
+Read each calendar event and filter by date. Extract:
+
+- Meeting title
+- Attendees (resolve to `[[People/Name]]` where possible)
+- Time/day
+- Description or agenda (if present)
+
+Filter out:
+
+- All-day placeholder events with no attendees ("Block", "OOO", "Focus time")
+- Declined events
+- Cancelled events
+
+### 1d. Read previous weekly (if exists)
+
+Check for last week's document:
+
+```bash
+ls "knowledge/Weeklies/{Person Name}/" | sort | tail -1
+```
+
+If it exists, read it to:
+
+- Carry forward any `[ ]` unchecked priorities
+- Note retrospective items that affect this week
+- Maintain continuity of ongoing themes
+
+## Step 2: Generate or Update
+
+### Creating a new weekly (start of week)
+
+1. **Focus:** Synthesize from highest-priority tasks and key meetings. What's
+   the main theme? Write one sentence.
+2. **Priorities:** Pull from task board:
+   - All `## In Progress` items first
+   - Then `high` priority `## Open` items
+   - Then items with due dates this week
+   - Carry forward incomplete priorities from last week
+   - Cap at 5-7 items. If more exist, prioritize ruthlessly.
+3. **Key Meetings:** From calendar. Format as
+   `**{Day}**: {title} with [[People/Name]] — {purpose}`. Look up attendees in
+   knowledge base to add context about purpose.
+4. **Blockers:** From task board's `## Blocked` section. Include what's needed
+   and from whom.
+5. **Accomplishments:** Leave empty (or pre-fill with anything completed Monday
+   morning).
+6. **Retrospective:** Leave empty.
+
+### Updating an existing weekly (mid-week)
+
+1. Re-read the task board for changes since the weekly was last updated.
+2. Mark completed priorities as `[x]`.
+3. Add new priorities that emerged (append to the list).
+4. Update blockers — remove resolved ones, add new ones.
+5. Add accomplishments as they happen.
+6. Do NOT touch the retrospective mid-week.
+
+### End-of-week update
+
+1. Final pass on priorities — mark all completed items `[x]`.
+2. Fill in accomplishments from the full week's activity (task board + People
+   note activity log).
+3. Write a brief retrospective:
+   - What went well?
+   - What didn't go as planned?
+   - What carries forward to next week?
+4. Note any unchecked priorities — these will carry forward to next week's
+   document.
+
+## Step 3: Write the Document
+
+### New weekly
+
+Ensure the person's subdirectory exists:
+
+```bash
+mkdir -p "knowledge/Weeklies/{Person Name}"
+```
+
+Write the full document to: `knowledge/Weeklies/{Person Name}/{YYYY}-W{WW}.md`
+
+### Existing weekly
+
+Use the Edit tool for targeted updates — mark items complete, add new entries,
+fill sections. Do NOT rewrite the entire file.
+
+## Step 4: Cross-reference
+
+After writing:
+
+- If new priorities were identified that aren't on the task board, add them to
+  the task board (the task board is canonical, the weekly references it).
+- If blockers were resolved, update the task board accordingly.
+- The weekly is a **snapshot that references** the task board — the task board
+  is the source of truth for task status.
+
+## Quality Checklist
+
+- [ ] ISO week number and date range are correct
+- [ ] Focus statement reflects the actual week theme (not generic)
+- [ ] Priorities pulled from task board (not invented)
+- [ ] Priorities capped at 5-7 items
+- [ ] Key meetings pulled from calendar (not guessed)
+- [ ] Meeting attendees resolved to `[[People/Name]]` where known
+- [ ] Blockers match task board's blocked items
+- [ ] Previous week's carry-forward items included
+- [ ] All backlinks use absolute paths
+- [ ] Retrospective only filled at end-of-week