diff --git a/.gitignore b/.gitignore index 303a196..2708d56 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ .cursor/ +.DS_Store +.vscode/ +.vscode \ No newline at end of file diff --git a/INDEX.md b/INDEX.md index d3efbcb..9b62b4c 100644 --- a/INDEX.md +++ b/INDEX.md @@ -163,6 +163,14 @@ A modular, retrieval-optimized knowledge base for AI coding agents building prod | review-ux | Reviewer | Critique user experience and interaction design | | review-production-readiness | Reviewer | Assess readiness for production deployment | +### Intern Productivity (`engineering-journal/`, `code-explainer/`, `question-formatter/`, `one-on-one-prep/`) +| Skill | Type | Summary | +|-------|------|---------| +| engineering-journal | Execution | Log debug sessions, learnings, and end-of-day reflections into a weekly journal | +| code-explainer | Execution | Explain code at any scope — file, directory, or full repo — with multiple depth modes | +| question-formatter | Execution | Turn vague problems into structured, answerable technical questions | +| one-on-one-prep | Execution | Prepare for 1:1 meetings with auto-pulled activity and guided reflection | + ## Usage Skills are loaded individually by AI agents based on task context. Each skill is self-contained with cross-references to related skills where deeper context is needed. diff --git a/README.md b/README.md index 416866c..4dbd2a3 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,99 @@ Draft RFCs and technical proposals from conversation context. Structures ideas i 1. Copy `rfc-drafter/SKILL.md` into your project's `.cursor/skills/rfc-drafter/` directory 2. Discuss a technical idea in conversation, then ask the agent to draft an RFC or proposal +### PR Description Generator + +**Path:** `pr-description/SKILL.md` + +Draft a pull request title and description from the current branch's commits and diff, filling in the repo's PR template if one exists. Optionally creates the PR via the GitHub CLI. + +**Requirements:** +- No external integrations required — works with local git only +- [GitHub CLI](https://cli.github.com/) (`gh`) if you want the skill to create the PR for you; otherwise it just drafts the markdown + +**Usage:** +1. Copy `pr-description/SKILL.md` into your project's `.cursor/skills/pr-description/` directory +2. Ask the agent to draft a PR description for the current branch + +### Self-Review Against Reviewer Checklists + +**Path:** `self-review/SKILL.md` + +Run a self-review of uncommitted or branch changes against this repo's existing reviewer checklists (`reviewers/review-*`), routing changed files to the relevant reviewers and producing one consolidated findings report. + +**Requirements:** +- The `reviewers/` skill files must be present alongside this skill (they already are in this repo) + +**Usage:** +1. Copy both `self-review/SKILL.md` and the `reviewers/` directory into your project's `.cursor/skills/` directory +2. Ask the agent to self-review your changes before opening a PR + +### Repo Orientation / Onboarding Guide + +**Path:** `repo-orientation/SKILL.md` + +Generate a repo orientation/onboarding guide by detecting the tech stack, mapping the directory structure, finding entry points, and summarising conventions, tooling, and CI/CD. + +**Requirements:** +- No external integrations required — works with the filesystem only + +**Usage:** +1. Copy `repo-orientation/SKILL.md` into your project's `.cursor/skills/repo-orientation/` directory +2. Ask the agent to generate an onboarding guide or help you understand the codebase + +### Engineering Journal + +**Path:** `engineering-journal/SKILL.md` + +Log debug sessions, learnings, and end-of-day reflections into a structured weekly journal. Combines rubber-duck debugging with a learning log. Entries are searchable and feed into 1:1 prep and weekly reports. + +**Requirements:** +- No external integrations required — works with the filesystem and git only + +**Usage:** +1. Copy `engineering-journal/SKILL.md` into your project's `.cursor/skills/engineering-journal/` directory +2. Ask the agent to log a debug session, record a learning, or do an end-of-day reflection + +### Code Explainer / Onboarding + +**Path:** `code-explainer/SKILL.md` + +Explain code at any scope — file, directory, or full repo. Supports quick scan, deep dive, system context, and onboarding map modes. Traces request paths, names patterns, flags newcomer traps, and cross-references knowledge skills. + +**Requirements:** +- No external integrations required — works with the filesystem and git only + +**Usage:** +1. Copy `code-explainer/SKILL.md` into your project's `.cursor/skills/code-explainer/` directory +2. Ask the agent to explain a file, walk through a module, or give you an onboarding map of the repo + +### Question Formatter + +**Path:** `question-formatter/SKILL.md` + +Turn a messy "it's not working" into a structured, answerable technical question. Guards against the XY Problem, auto-gathers code context and errors, and formats for Slack, GitHub, or verbal delivery. + +**Requirements:** +- No external integrations required — works with the filesystem and git only + +**Usage:** +1. Copy `question-formatter/SKILL.md` into your project's `.cursor/skills/question-formatter/` directory +2. Ask the agent to help you formulate a question for your team or format a question for Slack + +### 1:1 Prep + +**Path:** `one-on-one-prep/SKILL.md` + +Prepare for 1:1 meetings with your manager by auto-pulling recent work activity (commits, PRs, tickets) and prompting for reflection on wins, blockers, learning, and discussion topics. + +**Requirements:** +- [GitLens extension](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) with connected JIRA and/or GitHub integrations (optional — falls back to git log) +- GitKraken MCP server enabled in Cursor (optional) + +**Usage:** +1. Copy `one-on-one-prep/SKILL.md` into your project's `.cursor/skills/one-on-one-prep/` directory +2. Ask the agent to prepare for your 1:1 or prep for a meeting with your manager + ## License MIT diff --git a/code-explainer/SKILL.md b/code-explainer/SKILL.md new file mode 100644 index 0000000..6fe34e0 --- /dev/null +++ b/code-explainer/SKILL.md @@ -0,0 +1,287 @@ +--- +name: code-explainer +description: >- + Explain code at any scope — file, directory, or full repo. Supports quick scan, + deep dive, system context, and onboarding map modes. Traces request paths, names + patterns, flags newcomer traps, and cross-references knowledge skills. Use when + the user asks to explain code, understand a file, onboard to a codebase, walk + through how something works, or trace a code path. +--- + +# Code Explainer / Onboarding + +Explain code at any scope with the right level of depth for the situation. + +## Core Principle + +**Scope, read, explain, connect.** + +Determine what the user needs to understand and how deeply, gather the relevant code and context, then explain it concretely — with real names, real paths, and real patterns. Link to knowledge skills so explanations become learning opportunities. + +## Explanation Modes + +| Mode | Trigger phrases | Output | +|------|----------------|--------| +| **Quick scan** | "What does this do?", "Summarise this file" | 2-3 sentence summary, key exports, who calls it | +| **Deep dive** | "Walk me through this", "I need to modify this" | Section-by-section walkthrough, patterns, gotchas | +| **System context** | "How does this fit in?", "What calls this?" | Dependency map, data flow, upstream/downstream consumers | +| **Onboarding map** | "I'm new to this repo", "Where do I start?" | Directory overview, entry points, reading order | + +## Workflow + +### Step 1: Determine Scope and Mode + +Use `AskQuestion`: + +``` +AskQuestion: + title: "Code Explainer" + questions: + - id: scope + prompt: "What should I explain?" + options: + - "Current file (Recommended)" + - "A specific file or function" + - "A directory or module" + - "The whole repo (onboarding)" + - id: mode + prompt: "How deep should I go?" + options: + - "Quick scan — just tell me what it does (Recommended)" + - "Deep dive — walk me through everything" + - "System context — how it fits into the bigger picture" + - "Onboarding map — I'm new, where do I start?" +``` + +If the user already specified a file or asked a specific question in conversation, infer the scope and mode instead of asking. + +### Step 2: Gather Context + +Depending on the scope, gather: + +**For a single file:** +- Read the target file +- Read its imports to understand dependencies +- Detect the project's primary language from the manifest file (package.json → TypeScript/JavaScript, go.mod → Go, pyproject.toml/requirements.txt → Python, Cargo.toml → Rust, pom.xml/build.gradle → Java/Kotlin, Gemfile → Ruby). Then grep for imports using the appropriate extensions. **Always exclude** `node_modules`, `.git`, `vendor`, `dist`, and `build` directories via `--exclude-dir`: + - TypeScript/JavaScript: `Shell: grep -rn "import.*from.*[filename]" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build .` + - Python: `Shell: grep -rn "from.*[module].*import\|import.*[module]" --include="*.py" --exclude-dir=.git --exclude-dir=__pycache__ --exclude-dir=.venv .` + - Go: `Shell: grep -rn "\".*[package]\"" --include="*.go" --exclude-dir=.git --exclude-dir=vendor .` + - Rust: `Shell: grep -rn "use.*[module]\|mod.*[module]" --include="*.rs" --exclude-dir=.git --exclude-dir=target .` + - Java/Kotlin: `Shell: grep -rn "import.*[package]" --include="*.java" --include="*.kt" --exclude-dir=.git --exclude-dir=build --exclude-dir=target .` + - Ruby: `Shell: grep -rn "require.*[file]" --include="*.rb" --exclude-dir=.git --exclude-dir=vendor .` + - If unsure, use a broad search: `Shell: grep -rn "[filename]" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.go" --include="*.rs" --include="*.java" --include="*.kt" --include="*.rb" --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=vendor --exclude-dir=dist --exclude-dir=build .` +- `Shell: git log --oneline -10 [file]` — recent activity and contributors +- Check for a corresponding test file (e.g. `foo.test.ts`, `test_foo.py`) + +**For a directory or module:** +- `Shell: find [dir] -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.js" -o -name "*.jsx" -o -name "*.go" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/dist/*" | head -30` — list source files +- Read key entry point files (index.ts, main.py, mod.go, etc.) +- Read any README or documentation files in the directory + +**For the whole repo:** +- **Monorepo detection:** Before proceeding, check for monorepo indicators: + - `workspaces` field in `package.json` + - `pnpm-workspace.yaml` + - `lerna.json` + - Multiple `go.mod` files: `Shell: find . -maxdepth 3 -name "go.mod" | head -10` + - Multiple `package.json` files in subdirectories: `Shell: find . -maxdepth 2 -name "package.json" -not -path "./node_modules/*" | head -10` + + If a monorepo is detected, ask the user to scope: + + ``` + AskQuestion: + title: "Monorepo Detected" + questions: + - id: scope + prompt: "This looks like a monorepo with multiple projects. Which area should I focus on?" + options: + - "Give me the top-level overview first (Recommended)" + - "I'll specify a sub-project" + ``` + +- Read the top-level README if it exists +- `Shell: find . -maxdepth 2 -type f -name "*.md" | head -20` — find documentation +- `Shell: find . -maxdepth 1 -type d | sort` — top-level directory structure +- Read package.json, go.mod, pyproject.toml, Cargo.toml, or equivalent for dependencies +- Look for entry points: main.*, index.*, app.*, server.* + +### Step 3: Generate Explanation + +Use the template matching the selected mode. + +--- + +#### Quick Scan Template + +```markdown +## [filename] + +**Purpose:** [1-2 sentences — what this file does and why it exists] + +**Key exports:** +- `functionName()` — [what it does] +- `ClassName` — [what it represents] + +**Called by:** [list files that import this, or "entry point / not imported directly"] + +**Dependencies:** [key imports — what external libraries or internal modules it relies on] +``` + +--- + +#### Deep Dive Template + +```markdown +## [filename] — Deep Dive + +**Purpose:** [what this file does in the system] + +**Patterns used:** [name the design patterns — Repository, Factory, Observer, middleware chain, etc. If a relevant knowledge skill exists, reference it: "→ see `architecture/knowledge-design-patterns`"] + +### Section-by-section walkthrough + +#### [Section/block 1 name] (lines N-M) +[What this section does. Be concrete — use actual variable and function names. Explain the WHY, not just the what.] + +#### [Section/block 2 name] (lines N-M) +[Continue for each logical section] + +### Gotchas and newcomer traps +- [Thing that looks wrong but is intentional, with explanation] +- [Non-obvious side effect or implicit dependency] +- [Convention that differs from what you'd expect] + +### If you need to change this +[Practical guidance: "To add a new endpoint, you'd need to: 1. Add a route in routes.ts, 2. Create a handler in handlers/, 3. Add validation in schemas/. The test file is at test/foo.test.ts."] + +### Test coverage +- **Test file:** [path, or "No test file found"] +- **What's tested:** [brief summary of test cases] +- **What's not tested:** [any obvious gaps] + +### Recent activity +[Output of git log — who's been here recently, useful for knowing who to ask] +``` + +--- + +#### System Context Template + +```markdown +## [filename / module] — System Context + +**Role in the system:** [1-2 sentences — what job this component has] + +### Dependency map + +**This depends on:** +- `[module/file]` — [what it uses from it] +- `[module/file]` — [what it uses from it] + +**Depends on this:** +- `[module/file]` — [why it needs this] +- `[module/file]` — [why it needs this] + +### Data flow + +[Trace a concrete request or operation through the system. Example:] + +``` +User action → [Controller] → [Service] → [Repository] → [Database] + ↓ + [EventBus] → [NotificationService] → [Email provider] +``` + +[Explain each step with actual class/function names.] + +### Related knowledge +[Link to relevant architecture/knowledge skills if the codebase uses recognisable patterns: +- "This module follows hexagonal architecture → see `architecture/knowledge-hexagonal-architecture`" +- "The event handling uses pub/sub → see `architecture/knowledge-event-driven`"] +``` + +--- + +#### Onboarding Map Template + +```markdown +## Repo Onboarding Map + +**What this repo does:** [1-2 sentences — the product/service it provides] + +**Tech stack:** [languages, frameworks, databases, key libraries] + +### Directory structure + +| Directory | Purpose | +|-----------|---------| +| `src/` | [what's in here] | +| `tests/` | [test organisation] | +| `docs/` | [documentation] | +| ... | ... | + +### Start reading here + +[Ordered list of files to read to understand the codebase, with 1-sentence reason for each:] + +1. **`[file]`** — [why to read this first] +2. **`[file]`** — [what this teaches you about the architecture] +3. **`[file]`** — [the main business logic lives here] + +### Key entry points + +| Entry point | What triggers it | +|-------------|-----------------| +| `[file:function]` | [HTTP request, CLI command, cron job, event, etc.] | + +### Domain jargon glossary + +| Term | Meaning | Where you'll see it | +|------|---------|-------------------| +| `[DomainTerm]` | [Plain English definition] | [files/modules that use it] | + +### How to run it locally + +[Commands to get the project running — from README or inferred from package.json/Makefile/docker-compose] + +### Who to ask + +[From git log: who commits most frequently to which areas] + +| Area | Most active contributor | +|------|----------------------| +| `[directory]` | `[git username]` | + +### Related knowledge skills +[List any architecture/design patterns in use and link to the relevant knowledge skills] +``` + +### Step 4: Offer Follow-ups + +After presenting the explanation: + +``` +AskQuestion: + title: "What's next?" + questions: + - id: next + prompt: "Anything else you want to understand?" + options: + - "Done for now (Recommended)" + - "Deep dive into one of the dependencies" + - "Trace a specific request path" + - "Explain the test suite" + - "Show me how I'd make a change here" + - "Log what I learned (→ Engineering Journal)" + - "I have a question about this (→ Question Formatter)" +``` + +## Important Notes + +- **Be concrete, not abstract.** Use actual function names, file paths, and variable names. "It has a helper" is useless; "`normalizeEmail()` strips whitespace and lowercases the domain" is useful. +- **Name patterns explicitly.** If code uses Repository, Factory, Observer, middleware chain, or any recognisable pattern, name it. This teaches the reader to recognise patterns in the wild. +- **Flag newcomer traps.** Things that look broken but are intentional, implicit dependencies, magic strings, dynamic imports, runtime registration — anything that would trip up someone new. +- **Cross-reference knowledge skills.** When you spot a pattern covered by a skill in this repo (SOLID, hexagonal architecture, CQRS, etc.), mention it: "→ see `architecture/knowledge-hexagonal-architecture` for background on this pattern." +- **Don't fabricate.** If you're unsure what a section does, say so: "This block is unclear — it may handle [X] but I'd verify with the team." Never invent explanations. +- **Adapt to the language.** Use language-appropriate terminology (modules vs. packages, classes vs. structs, hooks vs. lifecycle methods). +- **Recent activity matters.** Always include `git log` output — knowing who recently touched a file tells the user who to ask questions to. This is especially valuable for interns. diff --git a/engineering-journal/SKILL.md b/engineering-journal/SKILL.md new file mode 100644 index 0000000..53fa9e5 --- /dev/null +++ b/engineering-journal/SKILL.md @@ -0,0 +1,391 @@ +--- +name: engineering-journal +description: >- + Log debug sessions, learnings, and end-of-day reflections into a structured + weekly engineering journal. Combines rubber-duck debugging with a learning log. + Auto-pulls git activity for context. Entries are searchable and feed into 1:1 + prep and weekly reports. Use when the user asks to log a debug session, record + something they learned, do an end-of-day reflection, or write a journal entry. +--- + +# Engineering Journal + +Log debug sessions and learnings into a structured, searchable weekly journal. + +## Core Principle + +**Debugging is learning. Capture both in one place.** + +Every debug session teaches something. Every learning has context. A single journal with typed entries keeps everything together and feeds into 1:1 prep and weekly reports. + +## Entry Types + +| Type | When to use | Key fields | +|------|------------|------------| +| **Debug** | Stuck on a problem, want to think through it | Symptom, hypothesis, investigation, root cause, lesson | +| **Learning** | Discovered something new — concept, tool, pattern, codebase quirk | Context, insight, why it matters | +| **Reflection** | End of day — guided review of the day's work | Pulls from both types above | + +## Workflow + +### Step 1: Determine Entry Type + +Use `AskQuestion`: + +``` +AskQuestion: + title: "Engineering Journal" + questions: + - id: entry_type + prompt: "What kind of entry?" + options: + - "Debug session — I'm stuck on something or just solved something" + - "Learning — I figured out something worth remembering" + - "End-of-day reflection (Recommended)" + - "Update an existing debug entry — resolve an open investigation" +``` + +Then follow the appropriate path below. + +--- + +### Path A: Debug Entry + +#### A0: Check for Open Investigations + +Before creating a new debug entry, check for existing unresolved entries: + +``` +Shell: grep -l "\\*\\*Status:\\*\\* Investigating" journal/*.md 2>/dev/null +``` + +If open entries are found, alert the user: + +> You have [N] open debug entry/entries still marked as "Investigating". Want to update one of those instead, or start a new entry? + +If the user wants to update, follow Path D. Otherwise continue to A1. + +#### A1: Gather Context + +Scan the current conversation for: +- **What is going wrong** (error messages, unexpected behaviour) +- **What was expected** (correct behaviour) +- **What has been tried** (steps taken, hypotheses tested) +- **What fixed it** (if already resolved) + +If the conversation doesn't contain enough detail, ask: + +``` +AskQuestion: + title: "Debug Entry" + questions: + - id: symptom + prompt: "What's the symptom? (error message, unexpected behaviour, etc.)" + options: + - "I'll describe it" + - id: status + prompt: "Is this resolved or still open?" + options: + - "Resolved — I found the fix" + - "Still investigating" +``` + +#### A2: Auto-Gather Technical Context + +Run these commands to enrich the entry: +- `git diff --stat` — what files have changed during the debug session +- `git log --oneline -5` — recent commits for context + +#### A3: Compose the Entry + +Use this template: + +```markdown +## Debug: [short descriptive title] + +**Date:** [YYYY-MM-DD] +**Status:** [Resolved | Investigating] +**Files involved:** [list from git diff or conversation] + +### Symptom +[What is going wrong — include error messages verbatim] + +### Expected behaviour +[What should happen instead] + +### Hypotheses +1. [First theory] — **Result:** [confirmed / ruled out / untested] +2. [Second theory] — **Result:** [confirmed / ruled out / untested] + +### Investigation log +- [Step taken] → [what was observed] +- [Step taken] → [what was observed] + +### Root cause +[What actually caused the problem. Write "TBD — still investigating" if unresolved] + +### Fix +[What fixed it, or "TBD" if unresolved. Include the actual code change or command if applicable] + +### Lesson +[What would you do differently next time? What mental model changed? What should you check first if you see similar symptoms?] +``` + +--- + +### Path B: Learning Entry + +#### B1: Prompt for the Learning + +If not already clear from conversation, ask: + +``` +AskQuestion: + title: "Learning Entry" + questions: + - id: topic + prompt: "What did you learn? (concept, tool, pattern, codebase quirk, etc.)" + options: + - "I'll describe it" + - id: source + prompt: "How did you learn it?" + options: + - "Figured it out while coding" + - "A teammate explained it" + - "Read docs or an article" + - "Code review feedback" +``` + +#### B2: Compose the Entry + +Use this template: + +```markdown +## Learned: [short descriptive title] + +**Date:** [YYYY-MM-DD] +**Source:** [How you learned it — coding, teammate, docs, code review] + +### Context +[What you were working on when you learned this] + +### Insight +[The thing you learned — explain it as if teaching someone else. Be specific: include code snippets, command examples, or configuration details where relevant] + +### Why it matters +[How does this change how you work? When will you use this again?] + +### Related +[Links to docs, files in the codebase, related skills, or people who helped] +``` + +--- + +### Path C: End-of-Day Reflection + +#### C1: Auto-Pull Today's Activity + +Gather data automatically: + +``` +Shell: git log --oneline --since="today" --author="$(git config user.name)" +``` + +Also check for any open debug entries from today that are still in "Investigating" status. + +#### C2: Prompt for Reflection + +Present the day's commits, then ask: + +``` +AskQuestion: + title: "End-of-Day Reflection" + questions: + - id: hardest + prompt: "What was the hardest thing you worked on today?" + options: + - "I'll describe it" + - id: learned + prompt: "Anything you figured out that you didn't know this morning?" + options: + - "Yes, I'll describe it" + - "Nothing major today" + - id: confused + prompt: "Anything still confusing that you want to revisit tomorrow?" + options: + - "Yes, I'll describe it" + - "All clear for now" +``` + +#### C3: Compose the Reflection + +Use this template: + +```markdown +## Reflection: [YYYY-MM-DD] + +**Date:** [YYYY-MM-DD] + +### What I worked on +[Summary from git log — list the main things, not every commit] + +### Hardest thing today +[From the user's answer — what made it hard, how they pushed through] + +### What I learned +[From the user's answer — or "Quiet day for new learnings" if nothing major] + +### Still fuzzy +[From the user's answer — things to revisit, questions to ask tomorrow] + +### Tomorrow's focus +[Infer from open work, or ask if not obvious] +``` + +--- + +### Step 2: Determine the Journal File + +Journal files are organised by ISO week: + +1. Calculate the current ISO week number and year +2. Target file: `journal/[YYYY]-W[WW].md` (e.g. `journal/2026-W28.md`) +3. If the file exists, **append** the new entry (add a horizontal rule `---` separator) +4. If the file doesn't exist, create it with a header: + +```markdown +# Engineering Journal — Week [WW], [YYYY] +``` + +Then append the entry below the header. + +Use `mkdir -p journal` to ensure the directory exists. + +### Step 3: Write the Entry + +1. Create the directory if needed: `Shell: mkdir -p journal` +2. If the weekly file exists, use `Edit` to append the entry after the last line +3. If the weekly file doesn't exist, use `Write` to create it with the header and entry +4. Report what was saved: + +> Journal entry saved to `journal/2026-W28.md` — "Debug: Redis connection timeout on cold start" + +### Step 4: Offer Follow-ups + +After saving, suggest relevant next actions: + +``` +AskQuestion: + title: "What's next?" + questions: + - id: next + prompt: "Entry saved. Anything else?" + options: + - "Done for now (Recommended)" + - "Add another entry" + - "Turn this into a question for my team (→ Question Formatter)" + - "Create a JIRA ticket for follow-up work" +``` + +--- + +### Path D: Update Existing Debug Entry + +#### D1: Find Open Entries + +Search for unresolved debug entries: + +``` +Shell: grep -n "\\*\\*Status:\\*\\* Investigating" journal/*.md +``` + +Present the list of open entries with their titles and dates. + +If no open entries are found, inform the user: + +> No open debug entries found. All previous debug sessions are resolved. + +#### D2: Select Entry to Update + +``` +AskQuestion: + title: "Update Debug Entry" + questions: + - id: entry + prompt: "Which entry do you want to update?" + options: + - "[Most recent investigating entry title] (Recommended)" + - "I'll specify which one" + - id: resolution + prompt: "What happened?" + options: + - "Found the root cause and fixed it" + - "Found the root cause, fix is pending" + - "Giving up / no longer relevant" +``` + +#### D3: Update the Entry + +Use `Edit` to update the existing entry in the weekly journal file: + +1. Change `**Status:** Investigating` → `**Status:** Resolved` +2. Fill in the `### Root cause` section with the user's description +3. Fill in the `### Fix` section with the actual fix +4. Fill in the `### Lesson` section — prompt the user if not obvious from conversation + +Report the update: + +> Updated debug entry in `journal/2026-W28.md` — "Debug: Redis connection timeout" → Resolved + +Then offer follow-ups (same as Step 4): + +``` +AskQuestion: + title: "What's next?" + questions: + - id: next + prompt: "Entry updated. Anything else?" + options: + - "Done for now (Recommended)" + - "Log what I learned from this (→ Learning entry)" + - "Turn this into a question for my team (→ Question Formatter)" + - "Create a JIRA ticket for follow-up work (→ JIRA Tickets)" +``` + +--- + +## Journal Format Contract + +Other skills in this repo depend on the journal's structure. If you change these, update the consuming skills. + +**Consuming skills:** `one-on-one-prep` + +| Element | Format | Used by | +|---------|--------|---------| +| Entry type heading | `## Debug:`, `## Learned:`, `## Reflection:` | one-on-one-prep (categorisation) | +| Status field | `**Status:** Resolved` or `**Status:** Investigating` | one-on-one-prep (wins vs blockers) | +| Date field | `**Date:** YYYY-MM-DD` | one-on-one-prep (period filtering) | +| Lesson field | `### Lesson` | one-on-one-prep (growth section) | +| Insight field | `### Insight` | one-on-one-prep (growth section) | +| File naming | `journal/YYYY-WNN.md` | one-on-one-prep (glob pattern) | + +## Reading Previous Entries + +When the user asks to review their journal: + +1. Use `Glob` to list files in `journal/` matching `*.md` +2. Show available weeks +3. Let the user pick a week or search by keyword +4. Display entries, optionally filtered by type (Debug / Learning / Reflection) + +## Important Notes + +- Journal files live in `journal/` at the project root by default. Create the directory if it doesn't exist. +- **Multi-repo setups:** If the user works across multiple repositories, suggest using a single shared journal location (e.g. `~/engineering-journal/`) instead of per-project journals. This avoids fragmenting entries across repos and ensures 1:1 prep can pull from all work. Offer this as a configuration option in Step 2 when the user first creates an entry. +- File naming uses ISO 8601 week dates: `YYYY-WNN.md` (e.g. `2026-W28.md`). +- Always **append** to existing weekly files, never overwrite. +- Date format within entries is ISO 8601 (`YYYY-MM-DD`). +- Debug entries with status "Investigating" should be flagged when the user starts a new debug entry — prompt them to update the old one. +- End-of-day reflections should reference debug and learning entries from the same day to avoid duplication — summarise rather than repeat. +- The `Lesson` field in debug entries and the `Insight` field in learning entries are the most valuable fields — encourage the user to be specific. "I learned about caching" is weak; "Redis SCAN is O(1) per call but O(N) total — don't use it in a request path" is useful. +- This journal integrates with the **1:1 Prep** skill — recent entries are pulled automatically to populate wins and growth sections. diff --git a/one-on-one-prep/SKILL.md b/one-on-one-prep/SKILL.md new file mode 100644 index 0000000..6e1b171 --- /dev/null +++ b/one-on-one-prep/SKILL.md @@ -0,0 +1,245 @@ +--- +name: one-on-one-prep +description: >- + Prepare for 1:1 meetings with your manager by auto-pulling recent work activity + (commits, PRs, tickets) and prompting for reflection on wins, blockers, learning, + and discussion topics. Pulls from the engineering journal if available. Use when + the user asks to prepare for a 1:1, prep for a meeting with their manager, or + wants a summary of what they've been working on for a check-in. +--- + +# 1:1 Prep + +Prepare structured notes for a 1:1 meeting with your manager. + +## Core Principle + +**Data first, then reflect. Show up prepared, not winging it.** + +Auto-pull your recent activity so you don't forget anything, then layer on the human parts — what you're proud of, where you're stuck, and what you want to talk about. + +## How This Differs From a Weekly Report + +| | Weekly Report | 1:1 Prep | +|---|---|---| +| **Perspective** | Backward-looking, factual | Forward-looking, reflective | +| **Audience** | Team / stakeholders | Your manager | +| **Purpose** | "Here's what I did" | "Here's what I need from you" | +| **Tone** | Professional summary | Candid, conversational bullets | + +## Workflow + +### Step 1: Confirm Parameters + +Use `AskQuestion`: + +``` +AskQuestion: + title: "1:1 Prep" + questions: + - id: period + prompt: "How far back should I look?" + options: + - "Since last 1:1 — I'll give the date" + - "Last 7 days (Recommended)" + - "Last 14 days" + - id: manager + prompt: "Who is your manager? (for framing the notes)" + options: + - "[Previous manager name from last saved 1:1 prep] (Recommended)" + - "I'll type their name" +``` + +If the user selects "Since last 1:1", ask for the date: + +``` +AskQuestion: + title: "Last 1:1 Date" + questions: + - id: last_meeting + prompt: "When was your last 1:1? (approximate is fine)" + options: + - "Last Monday" + - "Last Thursday" + - "I'll type the date" +``` + +### Step 2: Gather Activity Data + +Pull from all available sources **in parallel**: + +**Git commits:** +``` +Shell: git log --oneline --since="[period]" --author="$(git config user.name)" +``` + +**JIRA tickets (if available):** +``` +CallMcpTool: + server: user-eamodio.gitlens-extension-GitKraken + toolName: issues_assigned_to_me + arguments: + provider: "jira" +``` + +**GitHub PRs (open):** +``` +CallMcpTool: + server: user-eamodio.gitlens-extension-GitKraken + toolName: pull_request_assigned_to_me + arguments: + provider: "github" +``` + +**GitHub PRs (recently merged):** +``` +CallMcpTool: + server: user-eamodio.gitlens-extension-GitKraken + toolName: pull_request_assigned_to_me + arguments: + provider: "github" + is_closed: true +``` + +**Engineering journal (if available):** +``` +Glob: journal/*.md +``` + +Filter the results to only include files whose ISO week falls within the reporting period. For example, if the period is "Last 7 days" and today is 2026-07-15 (week 29), only read `journal/2026-W29.md` and `journal/2026-W28.md` (current and previous week). Discard journal files from older weeks. + +If journal files exist for the period, read them and extract: +- Debug entries with status "Resolved" → potential **wins** +- Learning entries → **growth** section +- Debug entries with status "Investigating" → potential **blockers** +- Reflection entries → **discussion topics** + +### Step 3: Prompt for Reflection + +Present the gathered activity summary, then ask the user for the parts that can't be automated: + +``` +AskQuestion: + title: "Reflect Before Your 1:1" + questions: + - id: wins + prompt: "Anything you're proud of that the data might not show? (helped a teammate, figured out something hard, etc.)" + options: + - "Yes, I'll describe it" + - "The data covers it" + - id: blockers + prompt: "Anything blocking you that your manager could help with?" + options: + - "Yes, I need help with something" + - "No blockers right now" + - id: growth + prompt: "Anything you want to learn or get better at?" + options: + - "Yes, I have something in mind" + - "Not sure yet" + - id: topics + prompt: "Anything else you want to discuss? (feedback, career, team, process, etc.)" + options: + - "Yes, I have a topic" + - "Nothing beyond the usual" +``` + +### Step 4: Compose the Prep Notes + +Use this template: + +```markdown +# 1:1 Prep — [date] + +**Period:** [start] – [end] +**Meeting with:** [manager name] + +## Wins + +[Things completed, shipped, or figured out. Pull from merged PRs, closed tickets, and resolved debug entries. Include the user's additions from the reflection prompt.] + +- Merged [PR #N](url) — [brief description] +- Closed [TICKET-N] — [brief description] +- [User-provided win] + +## Current Work + +[What's in progress right now. Pull from open PRs and active tickets.] + +- [PR #N](url) — [status: in review / WIP / waiting on feedback] +- [TICKET-N] — [brief description and status] + +## Blockers & Asks + +[The most important section. What do you need from your manager?] + +- **[Blocker description]** — What would help: [specific ask — review, decision, introduction, unblocking a dependency] + +[If no blockers: "No blockers right now."] + +## Learning & Growth + +[What you've learned recently and what you want to learn next. Pull from journal learning entries.] + +**Recently learned:** +- [Insight from journal or user input] + +**Want to explore:** +- [Area the user wants to grow in] + +## Discussion Topics + +[Anything else to bring up — feedback, career goals, team dynamics, process suggestions.] + +- [Topic from user input] + +--- + +*Prepared with data from [N] commits, [N] PRs, and [N] tickets.* +``` + +### Step 5: Present for Review + +Display the prep notes and ask: + +``` +AskQuestion: + title: "Review 1:1 Prep" + questions: + - id: approve + prompt: "Here are your 1:1 prep notes. How do they look?" + options: + - "Looks good (Recommended)" + - "I want to adjust some sections" + - "Save to a file" +``` + +### Step 6: Output + +Based on user choice: + +- **Looks good:** Display the final notes for the user to reference during the meeting. +- **Adjust:** Ask which sections to change and regenerate. +- **Save:** Write to `notes/one-on-one/[YYYY-MM-DD].md`. Create the directory if needed. + +## Tips for Effective 1:1s (Shown Once) + +The first time this skill is used, append these tips after the prep notes: + +> **Quick tips for your 1:1:** +> - Lead with blockers — this is the highest-value use of your manager's time +> - Be specific in your asks — "Can you review PR #42?" beats "I need help" +> - Share what you learned — it shows growth and helps your manager calibrate your projects +> - It's OK to say "I don't know" — that's more useful than pretending +> - Ask for feedback — "Is there anything I should be doing differently?" opens the door + +## Important Notes + +- The MCP tool calls reuse the same integrations as the `weekly-report` skill. If those aren't configured, fall back to git log only. +- If no JIRA/GitHub integrations are available, skip those sections gracefully — git commits alone are still useful. +- The engineering journal integration is optional — if no `journal/` directory exists, skip that data source and rely on user input for the growth/blocker sections. +- Keep the notes as **bullet points, not prose**. These are glance-during-the-meeting notes, not a formal document. +- The **Blockers & Asks** section should always frame problems as actionable requests. Not "deployment is broken" but "Deployment is blocked by the DNS migration — could you check with the platform team on the timeline?" +- If the user has been using the journal consistently, the reflection prompts will be much easier to answer since the data is already captured. Encourage journal use as a habit that pays off at 1:1 time. +- **Manager name persistence:** After the first use, check for previous 1:1 prep files in `notes/one-on-one/` to infer the manager name. Present it as a `(Recommended)` default in Step 1 rather than asking fresh each time. If no previous files exist, fall back to asking. +- **Journal format dependency:** This skill depends on the engineering journal's format contract (see `engineering-journal/SKILL.md` → "Journal Format Contract" section). If journal entry headings or status fields change, update the parsing logic in Step 2 accordingly. diff --git a/question-formatter/SKILL.md b/question-formatter/SKILL.md new file mode 100644 index 0000000..0667f0b --- /dev/null +++ b/question-formatter/SKILL.md @@ -0,0 +1,218 @@ +--- +name: question-formatter +description: >- + Turn a messy "it's not working" into a structured, answerable technical question. + Guards against the XY Problem, auto-gathers code context and errors, and formats + for Slack, GitHub, or verbal delivery. Use when the user wants to ask a question + to their team, post on Slack, write a GitHub comment, or needs help formulating + a technical question. +--- + +# Question Formatter + +Turn a vague problem description into a clear, well-structured technical question that gets fast answers. + +## Core Principle + +**A well-asked question gets answered in 5 minutes. A poorly-asked one gets ignored for 2 hours.** + +Structure the question so the reader immediately understands: what you're trying to do, what went wrong, and what you've already ruled out. + +## Why This Matters + +Senior engineers prioritise questions that are: +1. **Specific** — not "it's broken" but "the /api/users endpoint returns 500 when the email field contains a plus sign" +2. **Contextualised** — shows what you've already tried, so they don't suggest things you've ruled out +3. **Minimal** — includes only the relevant code, not the whole file +4. **Goal-oriented** — explains what you're ultimately trying to accomplish, not just your current approach + +## Workflow + +### Step 1: Understand the Problem + +Scan the current conversation for: +- **What went wrong** (error messages, unexpected behaviour) +- **What was expected** (correct behaviour) +- **What was tried** (debugging steps, attempted fixes) +- **What the user is working on** (broader task context) + +If the conversation doesn't contain enough, ask: + +``` +AskQuestion: + title: "Question Formatter" + questions: + - id: problem + prompt: "What's going wrong? (error, unexpected behaviour, confusion, etc.)" + options: + - "I'll describe it" + - id: goal + prompt: "What are you ultimately trying to accomplish? (not your current approach — the end goal)" + options: + - "I'll describe it" +``` + +### Step 2: XY Problem Guard + +The [XY Problem](https://xyproblem.info/) is when you ask about your attempted *solution* instead of the actual *problem*. This is especially common for interns who may not know the idiomatic approach yet. + +**Check:** Does the described problem match the stated goal? If the user says "How do I parse this regex?" but the goal is "I need to validate email addresses", the real question is about email validation, not regex. + +If you detect an XY mismatch, flag it: + +> It sounds like you're asking about [X], but your actual goal is [Y]. Senior engineers will give better help if you ask about [Y] directly. I'll frame the question around your real goal. + +### Step 3: Auto-Gather Technical Context + +Pull relevant context automatically: + +- **Current file snippet:** Read the file the user is working on. Extract only the relevant function or block — not the entire file. +- **Error messages:** If errors were mentioned in conversation, include them verbatim. +- **Git diff:** `Shell: git diff --stat` — shows what's been changed, useful for "it was working before". +- **Language/framework version:** Read from package.json, go.mod, requirements.txt, etc. + +### Step 4: Choose Output Format + +``` +AskQuestion: + title: "Output Format" + questions: + - id: format + prompt: "Where are you asking this question?" + options: + - "Slack message (Recommended)" + - "GitHub issue or PR comment" + - "Verbal — I'll ask in person or standup" +``` + +### Step 5: Compose the Question + +Use the template matching the format. + +--- + +#### Slack Format + +``` +*[Concise title of the question]* + +*What I'm trying to do:* +[1-2 sentences — the ultimate goal, not the attempted solution] + +*What's happening:* +[Concrete description of the problem — include error messages in a code block] + +*What I've tried:* +• [Step 1] → [result] +• [Step 2] → [result] + +*What I've ruled out:* +• [Thing checked that wasn't the cause] + +*Relevant code:* _(omit this section if the question is about process, infrastructure, or domain knowledge rather than code)_ +\`\`\`[language] +[Minimal code snippet — only what's needed to understand the problem] +\`\`\` + +*Environment:* [language version, framework, OS if relevant — omit if not applicable] + +Any pointers appreciated! +``` + +--- + +#### GitHub Format + +```markdown +## Question: [Concise title] + +### Goal +[What I'm ultimately trying to accomplish] + +### Problem +[What's going wrong — include error messages in code blocks] + +### What I've tried +- [Step 1] → [result] +- [Step 2] → [result] + +### What I've ruled out +- [Thing that isn't the cause and why] + +### Relevant code _(omit if not a code question)_ + +\`\`\`[language] +[Minimal snippet] +\`\`\` + +### Environment _(omit if not applicable)_ +- [Language/framework version] +- [OS if relevant] +- [Any relevant config] +``` + +--- + +#### Verbal Format + +A short, structured script for asking in person or at standup: + +``` +Hey [name], I've got a question about [area]. + +I'm trying to [goal]. + +I'm seeing [symptom] — here's the error: [key error message]. + +I've already checked [thing 1] and [thing 2], so I don't think it's [ruled-out cause]. + +My best guess is [hypothesis] — does that sound right, or am I looking in the wrong place? +``` + +--- + +### Step 6: Present for Review + +Display the formatted question and ask: + +``` +AskQuestion: + title: "Review Question" + questions: + - id: approve + prompt: "Here's your formatted question. How does it look?" + options: + - "Looks good, I'll send it (Recommended)" + - "I want to adjust it" + - "Switch to a different format" + - "Also log this as a debug entry (→ Engineering Journal)" +``` + +## Question Quality Checklist + +Before finalising, verify the question passes these checks: + +| Check | Pass? | +|-------|-------| +| States the **goal**, not just the attempted approach | | +| Includes a **concrete symptom** (error message, wrong output, unexpected behaviour) | | +| Shows **what was tried** with results | | +| Includes a **minimal code snippet** if the question involves code (not the whole file) | | +| Specifies **environment** where relevant | | +| Is **self-contained** — a reader doesn't need to ask "what do you mean?" | | + +## Important Notes + +- **Never include secrets, tokens, passwords, or API keys** in code snippets. Before including any code, scan for these patterns and replace matches with `[REDACTED]`: + - Variable names containing: `secret`, `password`, `passwd`, `token`, `api_key`, `apikey`, `api_secret`, `credential`, `private_key`, `access_key`, `secret_key` + - String literals matching: `Bearer `, `Basic `, `sk-`, `pk-`, `ghp_`, `gho_`, `github_pat_`, `xoxb-`, `xoxp-`, `AKIA` (AWS key prefix) + - PEM blocks: `-----BEGIN` + - Connection strings: `://.*:.*@` (contains embedded credentials) + - Environment variable references: `.env` file contents, `process.env.SECRET_*` + - See `security/knowledge-secure-by-design` for broader guidance on handling sensitive data. +- **Minimal snippets only.** A 5-line snippet gets read. A 50-line dump gets skipped. Trim to the smallest code that shows the problem. +- **Error messages verbatim.** Don't paraphrase errors — copy them exactly, including stack traces (trimmed to the relevant frames). +- **Don't answer the question.** This skill formats the question — it doesn't try to solve the problem. If you know the answer, tell the user directly instead of formatting a question. +- **Adapt the tone.** Slack is casual, GitHub is professional, verbal is conversational. Match the context. +- **Include what was ruled out.** This is the most underrated part. It saves the answerer from suggesting things you've already tried, and shows you did your homework. +- This skill integrates with the **Engineering Journal** — a well-formatted question can be logged as a debug entry after the problem is resolved.