ai-job-search/.claude/commands/expand.md

# /expand - Competency Expansion from Documents and Online Presence

You are enriching the candidate profile by discovering competencies hidden in documents and public online presence. This command is additive only — it never modifies existing profile content, only extends it.

Follow these steps **exactly in order**. Do not skip steps.

---

## Step 0: Read Existing Profile Files

Read these two files in parallel before doing anything else. You must know what is already there so you do not propose duplicates.

- `.claude/skills/job-application-assistant/01-candidate-profile.md`
- `.claude/skills/job-application-assistant/02-behavioral-profile.md`

Hold this content in context throughout the command. Do not re-read these files later.

---

## Step 1: Discovery — Scan All Sources

Scan every available source for "experience items" — anything that implies skill, knowledge, or competency. Process sources in this order.

### 1a. documents/cv/
Read all files in `documents/cv/`. Extract:
- Every course or module listed (including university coursework and online courses)
- Every certification mentioned, with issuer and date
- Every job responsibility bullet point (tools, methods, outcomes)
- Every independent project or side project
- Every volunteer or extracurricular role

### 1b. documents/linkedin/
Read all files in `documents/linkedin/`. Extract:
- Courses and certifications in the "Licenses & Certifications" section
- Skills and endorsements list
- Volunteer experiences
- Projects section
- Any platform-specific items not already found in the CV

### 1c. documents/diplomas/
Read all files in `documents/diplomas/`. Extract:
- All course/module names listed on transcripts
- Thesis title and subject area
- Any specialisation or track name

### 1d. documents/references/
Read all files in `documents/references/`. Extract:
- Competency language used by the referee (what skills or qualities they mention)
- Any specific projects, tools, or methods named

### 1e. GitHub Profile
Look up the GitHub username from `01-candidate-profile.md`. If a GitHub URL or username is present:

1. Use WebFetch or WebSearch to retrieve the public profile and pinned repositories
2. For each repository found:
   - Fetch the repository README
   - Note: name, description, primary language(s), topics/tags, any frameworks or libraries mentioned in the README
3. Also retrieve the full repository list if available (to catch unpinned repos)

If no GitHub username or URL is found in the profile, skip this source and note it was skipped.

### 1f. Other URLs in Profile
Check `01-candidate-profile.md` for any other URLs (portfolio site, personal website, Kaggle, Google Scholar, ResearchGate, publication links). For each:
- Fetch the page
- Extract any tools, methods, datasets, awards, or skills mentioned

---

## Step 2: Web Enrichment

For each experience item discovered in Step 1, search the web to extract the competencies it implies. Apply both approaches below — do not choose one over the other.

### Approach A: Direct lookup (explicit tools and frameworks)
If the item names a specific tool, framework, library, method, or platform, search for it directly:
- `"[Course name] [Provider] syllabus learning outcomes"`
- `"[Certification name] skills covered exam guide"`
- `"[Tool/framework name] skills what you learn"`

Fetch the most relevant page and extract the competency list.

### Approach B: Inferred competencies (from description and context)
For each item, regardless of whether Approach A found anything, also reason from the description:
- What problem domain does this item address?
- What methods, skills, or knowledge does someone need to do this work?
- What is the standard toolchain for this kind of work?

Combine both approaches into a single competency list for each item.

### Prioritise web lookup for:
- Named online courses (Coursera, edX, Udemy, LinkedIn Learning, DataCamp, fast.ai, etc.)
- Named certifications (AWS, GCP, Azure, Databricks, Tableau, etc.)
- University courses with a standard syllabus
- GitHub repositories with a README that names specific technologies

### Infer (without web lookup) for:
- Generic job responsibility bullets with no named tool
- Vague project descriptions
- Reference letter language (already phrased as competency — just record it)

---

## Step 3: Build Competency Map

After enriching all items, build a deduplicated competency map. Group findings into these categories:

**Technical Skills — Primary** (core languages, frameworks, methods you use regularly)  
**Technical Skills — Secondary** (tools you have used but are not primary)  
**Domain Knowledge** (subject matter expertise: geophysics, ML, NLP, etc.)  
**Methods and Practices** (agile, version control, reproducibility, testing, etc.)  
**Soft / Behavioral** (leadership, communication, collaboration signals from references and project descriptions)  

For each competency, record:
- The competency name
- The source item it came from (e.g. "Coursera — Deep Learning Specialisation", "GitHub — repo-name", "Reference letter — Jens Jensen")
- Whether it came from direct lookup (A), inference (B), or both

Remove anything already present in `01-candidate-profile.md` or `02-behavioral-profile.md`.

---

## Step 4: Present Grouped Summary

Present all new competencies for the user's review before writing anything. Format:

```
## /expand found [N] new competency signals across [M] sources

**COURSES & CERTIFICATIONS**
Source: [Course/cert name — Provider]
  + [Competency 1]
  + [Competency 2]
  ...

**GITHUB — [repo-name]**
Source: README + inferred from tech stack
  + [Competency 1]
  + [Competency 2]
  ...

**JOB RESPONSIBILITIES — [Company, Role]**
Source: CV bullets + direct tool lookup
  + [Competency 1]
  ...

**BEHAVIORAL SIGNALS**
Source: [Reference letter — Name / LinkedIn About / Project leadership]
  + [Signal 1]
  ...

[more sections as needed]
```

Then ask:

> **How would you like to proceed?**
>
> - **`all`** — Add everything above to your profile
> - **`review`** — I'll walk you through each source group one at a time
> - **`skip`** — Cancel without writing anything
>
> Or list specific groups to skip (e.g. "skip GitHub, add everything else").

Wait for the user's response before writing anything.

---

## Step 5: Write Confirmed Additions

Apply only the confirmed items. Use the Edit tool to add to the relevant sections of each file — do not rewrite entire files.

### Additions to `01-candidate-profile.md`
- Technical skills (primary and secondary) → append to the Technical Skills section
- Domain knowledge → append to the Domain Knowledge or Technical Skills section (match the existing structure)
- Methods and practices → append appropriately

For each addition, add a brief source annotation in a comment or parenthetical: *(Coursera — Deep Learning Specialisation)*, *(GitHub — project-name)*, etc. This makes future `/expand` runs idempotent.

### Additions to `02-behavioral-profile.md`
- Soft/behavioral signals → append to the "Strongest Behavioral Traits" or "How I Work Best" section (match existing structure)
- Always label inferred behavioral additions: *[Inferred from reference letter — Name / review before relying on this]*

---

## Step 6: Summary Report

After writing, present:

```
## /expand Complete

### Added to 01-candidate-profile.md
[List each competency added, with source]

### Added to 02-behavioral-profile.md
[List each behavioral signal added, with source]

### Sources processed
[List each source scanned and how many competencies it yielded]

### Sources skipped
[List any sources that were missing, empty, or yielded nothing new — with brief reason]

### Needs manual review
[Any items that were ambiguous, partially readable, or where web lookup returned no clear syllabus]
```

---

## Design Principles

- **Additive only.** This command never modifies existing profile content. It only appends.
- **Source-traceable.** Every addition records where it came from, so future runs are idempotent and the user can verify or remove individual items later.
- **Both approaches, always.** Web lookup and inference are applied together — not as alternatives. A named course gets its official syllabus AND a reasoned competency list.
- **User confirms before writing.** The full competency map is shown and confirmed before a single file is touched.
- **Behavioral signals are labeled.** Anything inferred from tone, language, or indirect signals is marked as inferred so it is reviewed critically.
- **GitHub is fully scanned.** All public repositories are checked, not just pinned ones — unpinned repos often contain significant competency signals.