swe-workflow-skills 0.1.0 → 0.3.0

package/skills/effort-estimation/SKILL.md

@@ -1,92 +1,49 @@
 ---
 name: effort-estimation
-description: "Estimate engineering effort with agile techniques — story points, t-shirt sizing, three-point estimation, capacity planning. Triggers: estimate this, how long will this take, story points, t-shirt sizing, effort estimation, capacity planning, sprint planning, budget estimate, forecast, velocity, when will this be done."
+description: "Estimate engineering effort with agile techniques — story points, t-shirt sizing, three-point estimation, capacity planning."
+when_to_use: "Triggers: estimate this, how long will this take, story points, t-shirt sizing, effort estimation, capacity planning, sprint planning, budget estimate, forecast, velocity, when will this be done."
 model: haiku
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
 
 # Effort Estimation
 
-Produce honest, useful estimates that help teams plan without creating false precision. Estimation in agile is about making informed decisions under uncertainty, not predicting the future exactly.
-
-## Core Philosophy
-
-**Estimates are forecasts, not commitments.** They communicate "based on what we know today, here's our best guess at the range of effort." They should always include uncertainty ranges, and they should improve as you learn more.
+Produce honest, useful estimates without false precision. Estimates are forecasts,
+not commitments — always ranges, always improving as you learn more.
 
 ## Workflow
 
 ### Step 1: Ensure Tasks Are Defined
 
-You can't estimate undefined work. Before estimating, ensure:
-
-- Tasks are broken down (use `feature-planning` if not)
-- Acceptance criteria exist for each task
-- Technical approach is at least sketched (spikes completed for unknowns)
-
-If the work is too vague to estimate, say so. "I can't estimate this until we do a spike" is a valid and responsible answer.
-
-### Step 2: Choose the Estimation Method
-
-| Method | Best For | Precision | Speed |
-|--------|----------|-----------|-------|
-| **T-shirt sizing** | Roadmap planning, early-stage sizing, large backlogs | Low (ranges) | Very fast |
-| **Story points** (Fibonacci) | Sprint planning, velocity tracking, mature teams | Medium (relative) | Moderate |
-| **Three-point estimation** | High-stakes estimates, budget requests, uncertain work | High (ranges with confidence) | Slow |
-| **Time-based** | Well-understood tasks with low uncertainty | High (hours/days) | Moderate |
-
-**Default recommendation**: T-shirt sizing for roadmap/quarter planning, story points for sprint planning. Three-point for budget requests and stakeholder communication.
+You can't estimate undefined work. Tasks must be broken down (use `feature-planning`
+if not), have acceptance criteria, and have at least a sketched technical approach.
+"I can't estimate this until we do a spike" is a valid and responsible answer.
 
-### Step 3: Apply the Method
+### Step 2: Choose the Method
 
-See [references/estimation-methods.md](references/estimation-methods.md) for detailed guidance on each method.
+T-shirt sizing for roadmap and early-stage sizing; story points (Fibonacci) for
+sprint planning and velocity tracking; three-point estimation for budget requests
+and high-uncertainty, high-stakes work; time-based only for well-understood tasks.
+See [references/estimation-methods.md](references/estimation-methods.md) for
+detailed guidance on each method.
 
-**Key principles across all methods:**
+### Step 3: Apply It
 
-1. **Estimate as a team**, not individually. The person most and least familiar with the area should both contribute — the gap reveals hidden complexity.
-2. **Estimate relative to known work**, not in absolute terms. "This is about twice as hard as that login feature we built" is more accurate than "this will take 3 days."
-3. **Include uncertainty explicitly.** "3-5 days" is more honest than "4 days."
-4. **Estimate the work, not the worker.** Story points measure the task's size, not who's doing it.
-5. **Re-estimate when you learn more.** Initial estimates are educated guesses. Update them as spikes complete and requirements clarify.
+Estimate per task, not the project as a single unit; relative to known work rather
+than in absolute terms; as a team where possible (the familiarity gap between
+estimators reveals hidden complexity); with uncertainty explicit. Re-estimate when
+spikes complete or requirements clarify.
 
-### Step 4: Handle Budget and Timeline Requests
+### Step 4: Translate for Stakeholders
 
-When stakeholders need dates or dollars, translate estimates thoughtfully:
-
-**From story points to time:**
-```
-Estimated story points for the project: 85
-Team velocity: ~30 points per sprint (2-week sprints)
-Sprints needed: 85 / 30 = ~3 sprints = 6 weeks
-
-Add buffer for unknowns (20-30%): 7-8 weeks
-Communicate as range: "6-8 weeks with the current team"
-```
-
-**From effort to cost:**
-```
-Effort estimate: 12-16 person-weeks
-Team loaded cost: $X per person-week
-Total: 12 × $X to 16 × $X
-Communicate as range: "$A - $B"
-```
-
-**Always provide ranges, never single numbers.** A single number becomes a commitment; a range communicates confidence.
+Convert to time or cost via team velocity or loaded cost, add a 20-30% buffer for
+unknowns, and communicate a range in stakeholder language — weeks and dollars, not
+story points. A single number becomes a commitment; a range communicates confidence.
 
 ### Step 5: Track and Calibrate
 
-Estimates improve with feedback. After each sprint or project:
-
-- Compare estimated vs actual effort
-- Identify systematic patterns (always overestimate UI? Always underestimate integrations?)
-- Adjust team velocity based on recent data (use the last 3-5 sprints, not all-time average)
-
-## Common Estimation Traps
-
-- **Anchoring**: The first number said influences everyone else. Use blind estimation (planning poker, simultaneous reveal).
-- **Planning fallacy**: People consistently underestimate. Use historical data to calibrate.
-- **Scope creep blindness**: Estimate the work as defined, then add buffer for scope growth — it always grows.
-- **Hero planning**: Estimating based on the best-case scenario with the best developer with zero interruptions. Estimate for a typical day with meetings and context switches.
-- **Precision theater**: Saying "47 hours" when you mean "roughly a week." False precision erodes trust faster than honest ranges.
+Compare estimated vs actual each sprint, look for systematic bias, and recalibrate
+velocity on the last 3-5 sprints, not the all-time average.
 
 ## Principles Applied
 

package/skills/exploratory-data-analysis/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: exploratory-data-analysis
+description: "Explore and profile an unfamiliar dataset before modeling or analysis — structural profiling, missingness structure, distributions and outliers, feature–target relationships, leakage awareness, and explicit hypothesis generation. Pipeline-level data trust (broken dashboards, tests, contracts, freshness) → data-quality; formal inference on the hypotheses → statistical-analysis."
+when_to_use: "Triggers: explore this dataset, EDA, profile the data, what's in this data, first look at the data, understand this CSV, distributions, outliers, missing values, correlation, data leakage."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# Exploratory Data Analysis
+
+Understand a dataset before trusting it with a model or a decision. The output
+of EDA is not a pile of statistics — it is a documented understanding: what the
+data is, what's wrong or surprising in it, and a set of explicit hypotheses to
+test next. Every step below feeds that document.
+
+## Workflow
+
+### 1. Frame the goal and the grain
+
+Before profiling anything, write down what decision or model this data will
+feed, and establish the **grain**: what does one row represent (an order? a
+customer? a customer-month?)? Duplicate keys and mixed grains invalidate every
+later statistic. If the eventual use is prediction, note *when* the prediction
+would be made — that timestamp drives the leakage checks in step 5.
+
+### 2. Profile structurally
+
+Column types, ranges, cardinality, and summary statistics for every column —
+cheaply, before any deep dive. Triage wide tables by metadata first (null rate,
+cardinality, type) and prioritize columns by relevance to the goal; don't
+profile 400 columns equally.
+
+If the data doesn't fit in memory: push aggregations down to the warehouse
+(SQL), or use an out-of-core/lazy engine (DuckDB, Polars). When you sample,
+**sample representatively** — random or stratified, never `head()` (files are
+usually ordered by time or id) — and state the caveat that rare events and
+extreme outliers can be missed under sampling; verify those against the full
+data with targeted queries.
+
+### 3. Map the missingness structure
+
+Null counts are the start, not the answer. Distinguish:
+
+- **Random gaps** — sporadic nulls, roughly uniform across segments.
+- **Structural missingness** — a column populated only for some segment, after
+  some date, or by some source system. Cross-tab null rates against segments
+  and time to find these.
+- **Informative missingness** — where the *fact* that a value is missing
+  predicts the outcome (e.g., income missing for churned users). Flag it; it
+  may be a feature, or it may be leakage.
+
+Also check for disguised missing values: sentinel codes (0, -1, 999,
+"unknown", empty string) that aren't NULL.
+
+### 4. Distributions and outliers
+
+For key numeric columns: quantiles, histograms, and an outlier pass (IQR or
+similar). For categoricals: frequency tables and rare-level counts. Decide for
+each outlier cluster whether it is a data error, a unit mismatch, or a genuine
+tail — **never drop outliers before classifying them**; genuine tails are often
+the interesting part. Check skew before assuming any statistic (mean, std) is
+representative.
+
+### 5. Target definition, balance, and leakage
+
+If the data will feed a model:
+
+- **Define the target explicitly** (e.g., "churn = no order in 90 days after
+  cutoff") and check its **class balance** — a 2% positive rate changes the
+  whole modeling and evaluation approach downstream.
+- **Hunt for leakage**: any column recorded at-or-after the outcome
+  (cancellation reason, final status, updated_at aggregates), and proxies that
+  encode the outcome indirectly. Test: "would this value exist at prediction
+  time?" If unsure, trace how the column is produced. A too-good correlation
+  with the target is a leakage smell, not a win.
+
+### 6. Relationships, not just profiles
+
+Univariate profiles alone don't generate hypotheses. Examine bivariate
+structure: correlations among candidate features, and each candidate feature
+against the target (grouped rates, means by decile, simple cross-tabs). Note
+confounders — a feature↔target association may be explained by segment or
+time. This is where most real hypotheses come from.
+
+### 7. Write the hypotheses and hand off
+
+Close with a short findings document: data issues found, columns excluded and
+why (especially leakage suspects), and **explicit hypotheses phrased as
+testable statements** ("weekend signups churn more", "the price effect is
+driven by segment X") plus open questions for the data owners. Formal testing
+of those hypotheses is `statistical-analysis` territory; feature/training
+pipeline work is `ml-pipeline-design`.
+
+## Principles
+
+- **KISS**: value counts and group-by rates beat clever visualizations for
+  finding problems fast.
+- **YAGNI**: profile to the goal — an exhaustive 400-column report nobody reads
+  is not EDA.
+- **Honest accounting**: record what you did NOT check (columns skipped,
+  sample-size limits) in the findings doc.
+
+## Cross-skill boundaries
+
+- Bad data in a *pipeline or dashboard* (freshness, contracts, dbt tests,
+  lineage) → **data-quality** — that's an operational trust problem, not
+  exploration of an unfamiliar dataset.
+- Formal hypothesis testing, experiment design, significance → **statistical-analysis**.
+- Turning the analysis into scheduled production code → **notebook-to-production**.
+- Schema design for storing the data → **data-modeling**.

package/skills/exploratory-data-analysis/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "skill_name": "exploratory-data-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I just got a CSV export of our customer orders — about 200k rows, 30 columns — and I've never seen this data before. We eventually want a churn model out of it. Where do I start?",
+      "expected_output": "Should run a structured EDA workflow: profile columns first, examine missingness patterns and distributions, look at the target definition and class balance, flag potential leakage columns, and turn findings into explicit hypotheses — not jump to modeling.",
+      "assertions": [
+        "Profiles the dataset first (column types, ranges, cardinality, summary statistics) before giving any modeling advice",
+        "Examines missingness patterns and distinguishes random gaps from structural ones (e.g., a column only populated for some segment)",
+        "Checks distributions and flags outliers or skew with concrete methods (quantiles, histograms, IQR or similar)",
+        "Warns about target leakage — columns that would not be available at prediction time must be identified and excluded",
+        "Examines how the churn target would be defined and its class balance before any modeling",
+        "Looks at relationships between candidate features and the target, not just univariate profiles",
+        "Produces explicit hypotheses or follow-up questions from the findings rather than only reporting statistics"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need to understand a warehouse extract with 400 columns and 3 million rows by Friday, and pandas kills my laptop when I load it. What's the plan?",
+      "expected_output": "Should scale the EDA workflow instead of abandoning it: triage columns cheaply first, work on a representative sample or push aggregations to the warehouse, and prioritize by the analysis goal rather than exhaustively profiling everything.",
+      "assertions": [
+        "Recommends sampling or chunked/out-of-core processing instead of loading everything into memory",
+        "Notes the sample must be representative (random or stratified) and flags the caveat that rare events and outliers can be missed under sampling",
+        "Triages the 400 columns cheaply (types, null rates, cardinality) before deep-diving any of them",
+        "Prioritizes columns by relevance to the stated goal rather than profiling all 400 equally",
+        "Suggests pushing heavy aggregations down to the warehouse via SQL, or using a lazy/out-of-core engine (e.g., Polars, DuckDB, Dask)",
+        "Still covers the core EDA checklist (types, missingness, distributions, key relationships) on the reduced view"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our finance dashboard has shown wrong revenue numbers all week — the nightly job loads orders into the warehouse and something is off upstream. Can you help me analyze the data and find the problem?",
+      "expected_output": "Should recognize this as a pipeline-level data-trust problem, not exploration of an unfamiliar dataset — hand off to the data-quality skill (dbt tests, freshness, schema drift, contracts, lineage) rather than starting a dataset-profiling workflow.",
+      "assertions": [
+        "Recognizes this as a data-quality / pipeline-trust problem rather than exploratory analysis of a new dataset",
+        "Hands off to or invokes the data-quality skill instead of running a generic EDA workflow",
+        "Points at concrete data-quality directions (dbt tests, source freshness, schema drift, upstream contract, lineage/blast radius) as the right path",
+        "Does not respond with a dataset-profiling/distributions workflow as the primary answer"
+      ]
+    }
+  ]
+}

package/skills/feature-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-planning
-description: "Break features into well-scoped tasks with acceptance criteria, risk assessment, and dependency mapping. Triggers: plan this, break this down, scope this feature, create tasks for, sprint planning, how should I implement this feature, user stories, acceptance criteria, dependency mapping, feature breakdown."
+description: "Break features into well-scoped tasks with acceptance criteria, risk assessment, and dependency mapping. Triggers: plan this, break this down, scope this feature, create tasks for, sprint planning, how should I implement this feature, user stories, acceptance criteria, dependency mapping, feature breakdown. Creates the plan — executing an already-approved plan checkpoint by checkpoint → plan-execution."
 model: sonnet
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
@@ -82,3 +82,7 @@ Output the complete plan using the template at [templates/plan.md](templates/pla
 If the feature involves architectural decisions (new services, database changes, API design), suggest using the `architecture-design` skill before finalizing the plan.
 
 If the feature requires data model changes, suggest using the `data-modeling` skill for that portion.
+
+If the idea itself is still fuzzy — the user is exploring what to build rather than how — run `brainstorming` first; this skill converges, that one diverges.
+
+Once the plan is approved and execution begins, the `plan-execution` skill takes over: checkpointed batches, verification evidence per checkpoint, and drift-triggered re-planning (which loops back here).

package/skills/finops-cost-optimization/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: finops-cost-optimization
+description: "Understand and reduce cloud spend — cost visibility and allocation (tagging, ownership), unit economics, rightsizing, autoscaling, commitment discounts (reserved instances, savings plans), storage/egress traps, architecture cost review, budgets and anomaly alerts. Triggers: cloud costs, AWS bill, cut costs, cost optimization, FinOps, why is our bill so high, rightsizing, reserved instances, savings plan, egress fees, cost per customer. Whether to build or buy a capability → build-vs-buy; making code faster → performance-optimization."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash, WebFetch, WebSearch
+---
+
+# FinOps & Cost Optimization
+
+Treat cloud cost as an engineering metric — observable, attributed, and
+optimized with the same rigor as latency. The failure mode this skill counters:
+nobody owns the bill, so it only gets attention as a quarterly surprise, and
+the response is a panicked freeze instead of systematic reduction. Boundaries:
+`performance-optimization` makes code faster (sometimes cheaper as a side
+effect); `build-vs-buy` decides whether to run the capability at all; this
+skill optimizes what you *do* run.
+
+## Workflow
+
+### Step 1: Visibility Before Optimization
+
+You can't cut what you can't attribute. Establish first:
+
+- **Allocation**: tag/label resources by service, team, and environment;
+  measure the untagged remainder and drive it down — an 40%-unattributed bill
+  makes every later step guesswork.
+- **The big rocks**: rank spend by service and by resource type. Cloud bills
+  follow a power law; the top 5 line items usually carry most of the total.
+  Optimizing anything outside them is procrastination with charts.
+- **Trend vs events**: is spend growing with usage (fine, if unit costs hold),
+  or did it step-change with a deploy (an incident with a dollar signature)?
+
+Pull real billing data (cost explorer exports, `infracost` on IaC diffs, the
+provider CLIs) — never optimize from memory of last quarter's bill.
+
+### Step 2: Define Unit Economics
+
+Total spend is noise; **cost per unit of value** — per customer, per request,
+per GB processed, per model inference — is signal. A bill that doubles while
+customers triple is a win. Pick 1–3 unit metrics with the team, compute them
+from the Step-1 allocation, and make them the number optimization is judged by.
+This is also what connects engineering to the business conversation
+(`metrics-and-okrs`).
+
+### Step 3: Harvest the Waste (no architecture changes)
+
+The reliable first wins, in typical order of return:
+
+- **Orphans**: unattached volumes/IPs, forgotten environments, snapshots-forever,
+  idle dev clusters running nights and weekends (schedule them off).
+- **Rightsizing**: instances/databases provisioned for imagined peak — check
+  actual utilization (single-digit CPU on a large instance is a purchase order
+  for the cloud provider, not capacity planning).
+- **Storage classes & lifecycle**: hot-tier data nobody has read in a year;
+  logs and backups with no expiry — lifecycle policies are one-line fixes.
+- **Non-prod parity**: staging doesn't need production's instance sizes,
+  replica counts, or retention.
+
+### Step 4: Buy Commitment for the Stable Baseline
+
+After rightsizing (never before — you'd lock in the waste): cover the stable,
+predictable baseline with reserved instances / savings plans / committed-use
+discounts, and keep the spiky remainder on-demand or spot (spot for
+interruption-tolerant work: batch, CI, stateless workers). Start conservative
+(cover well under 100% of the baseline) and ratchet up as forecasts prove out —
+over-commitment converts a variable cost into a fixed regret.
+
+### Step 5: Review the Architecture's Cost Shape
+
+Some spend is structural, and only architecture changes move it:
+
+- **Egress and cross-zone/region chatter** — the classic invisible line item;
+  co-locate chatty services, cache at the edge, compress.
+- **Per-invocation pricing at scale** — serverless that grew past the
+  crossover where instances are cheaper (and vice versa: idle instances that
+  should be serverless).
+- **Managed-premium vs ops-burden** — the managed service's markup is often
+  worth it (that's a `build-vs-buy` call when it gets big).
+- **Data pipelines** — scan-based pricing (warehouse queries over unpartitioned
+  tables) and always-on streaming for hourly-batch needs (`data-pipeline-design`).
+
+Cost these with current provider pricing (verify live — pricing changes), and
+record significant trade-offs as ADRs (`architecture-design`).
+
+### Step 6: Keep It Continuous
+
+- **Budgets + anomaly alerts** per team/service, routed to the owning team —
+  a cost regression is a defect, detected in days not quarters.
+- **Cost in the deploy loop**: IaC cost diffs (e.g. infracost) in PRs makes
+  cost visible at decision time.
+- **A monthly 30-minute review** of the unit metrics and top movers beats an
+  annual cost-cutting project.
+
+## Principles Applied
+
+- **Attribution before optimization** — unowned costs never stay cut.
+- **Unit economics over totals** — growth should raise the bill; only rising
+  *unit* cost is a problem.
+- **Biggest line item first** — a 10% cut of the top item beats a 90% cut of
+  the tenth.
+
+## Cross-Skill References
+
+- `build-vs-buy` — whether to run the capability at all; managed-vs-self-hosted TCO
+- `performance-optimization` — efficiency work that reduces compute per request
+- `architecture-design` — recording cost-driven structural decisions as ADRs
+- `observability-design` — the metrics/alerting machinery cost signals ride on
+- `data-pipeline-design` — cost-shaping batch/streaming and warehouse workloads
+- `metrics-and-okrs` — tying unit economics to business metrics

package/skills/finops-cost-optimization/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "finops-cost-optimization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our AWS bill jumped from $18k to $31k/month over the last two quarters and leadership wants it 'fixed'. Where do we start?",
+      "expected_output": "Starts with visibility, not cuts: attribute the spend (tagging/allocation), rank the top line items, and separate usage-driven growth from step-change regressions; defines unit economics (cost per customer/request) as the real judge; then harvests waste in order of return (orphans, rightsizing from actual utilization, storage lifecycle, non-prod schedules), only then commitment discounts on the post-rightsizing baseline, plus budgets/anomaly alerts so the next jump is caught in days",
+      "assertions": [
+        "Establishes visibility and attribution first (tagging/allocation, ranking top line items from real billing data) before proposing any cuts",
+        "Distinguishes usage-driven growth from step-change regressions and/or introduces unit economics (cost per customer/request) rather than treating the total as the metric",
+        "Proposes concrete waste harvesting: orphaned resources, rightsizing based on actual utilization, storage lifecycle policies, or scheduling non-prod environments off",
+        "Recommends commitment discounts (RIs/savings plans) only after rightsizing, covering a conservative stable baseline",
+        "Sets up continuous guardrails: budgets and anomaly alerts routed to owning teams, and/or cost checks in the deploy loop"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our bill is dominated by data transfer: about 40% is inter-AZ traffic and NAT gateway charges between our microservices, and the rest of the top items are a Kafka cluster and a data warehouse where queries scan whole tables. Rightsizing won't move these. What are our options?",
+      "expected_output": "Recognizes structural/architectural cost shape: co-locating chatty services or reworking cross-AZ topology (weighing the availability trade-off), VPC endpoints / NAT alternatives, compression; warehouse scan costs via partitioning/clustering and incremental models; evaluates whether always-on streaming matches the actual latency need; recommends costing options with live pricing and recording the trade-offs as ADRs since these decisions trade resilience/latency for money",
+      "assertions": [
+        "Recognizes these as architecture-shaped costs that rightsizing cannot fix and addresses the egress/inter-AZ problem specifically (co-location, topology, VPC endpoints, compression)",
+        "Notes the availability/resilience trade-off in reducing cross-AZ traffic rather than recommending single-AZ blindly",
+        "Addresses the warehouse scan costs structurally (partitioning, clustering, incremental models) rather than only suggesting fewer queries",
+        "Questions whether the always-on streaming infrastructure matches the actual latency requirement (batch vs streaming)",
+        "Recommends verifying costs against current provider pricing and/or recording significant cost-driven decisions as ADRs"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our checkout API's p99 latency is 4 seconds and profiling shows an N+1 query pattern plus a missing index. Can you help optimize it?",
+      "expected_output": "Recognizes this as code/query performance work, not cloud-spend optimization — refers to performance-optimization for the N+1 and indexing work, noting the boundary: performance-optimization makes code faster (sometimes cheaper as a side effect); finops-cost-optimization attributes and reduces cloud spend",
+      "assertions": [
+        "Recognizes the request as application performance optimization, not cloud cost management",
+        "Refers to the performance-optimization skill for the N+1/indexing work",
+        "Does not produce a FinOps workflow (tagging, rightsizing, commitments) as the answer",
+        "States or implies the boundary: performance-optimization owns making code fast; finops-cost-optimization owns understanding and reducing spend"
+      ]
+    }
+  ]
+}

package/skills/git-workflow/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: git-workflow
-description: "Write commit messages, PR descriptions, and manage branching strategy following conventional commits. Triggers: write a commit message, commit this, PR description, pull request, branching strategy, git workflow, squash commits, rebase, conventional commits, how should I commit this, review staged changes."
+description: "Write commit messages, PR descriptions, and manage branching strategy following conventional commits."
+when_to_use: "Triggers: write a commit message, commit this, PR description, pull request, branching strategy, git workflow, squash commits, rebase, conventional commits, how should I commit this, review staged changes."
 model: haiku
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
@@ -13,11 +14,13 @@ Help write clear commit messages, structured PR descriptions, and manage branchi
 
 ### Step 1: Analyze the Changes
 
-Read the staged changes to understand what was done:
+Currently staged (live at skill load; empty when nothing is staged, this isn't a
+git repo, or injection is disabled):
 
-```bash
-git diff --staged
-```
+!`git diff --staged --stat 2>/dev/null || true`
+
+If the summary above is empty or not enough to understand the change, run
+`git diff --staged` yourself for the full diff.
 
 Identify:
 - **What changed?** (files modified, functions added/removed, logic altered)
@@ -52,6 +55,10 @@ Use the Conventional Commits format — see [references/conventions.md](referenc
 - Breaking changes: `BREAKING CHANGE: description`
 - Co-authors: `Co-authored-by: Name <email>`
 
+Commit types are not just style — in automated release flows they drive the version:
+`fix` → PATCH, `feat` → MINOR, `feat!`/`BREAKING CHANGE:` → MAJOR. A mislabeled type
+mis-versions the next release (see `release-management`).
+
 ### Step 3: Validate
 
 Before committing, check:
@@ -64,14 +71,17 @@ Before committing, check:
 
 ### Step 1: Analyze the Branch
 
-Read the changes in the branch:
+Branch state vs the default branch (live at skill load; tries `main` then
+`master`):
 
-```bash
-git log main..HEAD --oneline
-git diff main...HEAD --stat
-```
+!`git log main..HEAD --oneline 2>/dev/null || git log master..HEAD --oneline 2>/dev/null || true`
 
-Understand the full scope of changes across all commits.
+!`git diff main...HEAD --stat 2>/dev/null || git diff master...HEAD --stat 2>/dev/null || true`
+
+If the output above is empty or the repo uses a different default branch, run the
+equivalents against the actual base branch. Understand the full scope of changes
+across all commits — run the full `git diff <base>...HEAD` when the stat summary
+isn't enough.
 
 ### Step 2: Write the PR Description
 
@@ -102,9 +112,10 @@ Help set up or improve branching conventions. Ask about team size and release ca
 
 **For small teams (1-5 devs) or continuous deployment:**
 - `main` — always deployable
-- `feat/description` — feature branches, short-lived (1-3 days)
-- `fix/description` — bug fix branches
-- Merge to main via PR, deploy from main
+- Branch naming: `feat/<description>`, `fix/<description>` — short-lived (1-3 days)
+- Merge to main via PR — **squash-merge by default** (one clean commit per logical
+  change on main); one approval is the right review bar at this size
+- Deploy from main
 
 **For medium teams (5-15 devs) or scheduled releases:**
 - `main` — production
@@ -125,3 +136,9 @@ See [references/conventions.md](references/conventions.md) for branch naming con
 - **KISS**: One commit = one logical change. Don't bundle unrelated changes.
 - **DRY**: If you're writing the same commit message pattern repeatedly, you might be making commits too granular or too broad.
 - **Functional Independence**: Each PR should be independently deployable when possible. Avoid PRs that depend on other unmerged PRs.
+
+## Cross-Skill References
+
+- `release-management` — cutting the release these commits accumulate into: semver, changelog, tagging, publishing
+- `code-reviewing` — reviewing the PR the description introduces
+- `verification-before-completion` — run the proving commands before pushing or opening the PR

package/skills/llm-app-engineering/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: llm-app-engineering
+description: "Design and build LLM-powered applications — prompt and context engineering, RAG architecture (chunking, hybrid retrieval, reranking, grounded prompts), agent design (tool surfaces, planning, sub-agents), and memory. Triggers: build a chatbot, LLM app, AI assistant, prompt engineering, system prompt, RAG design, chunking, embeddings, vector database, semantic search, AI agent, tool calling, agent memory, context window, hallucinations. Measuring quality → ai-evaluation; model serving/inference infra → ml-model-deployment."
+model: opus
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+---
+
+# LLM App Engineering
+
+Design LLM applications as **systems, not prompts**: what goes into the context
+window, what the model is allowed to do, and what happens when it's wrong. The
+model is the one component you don't control — engineer everything around it.
+This skill designs and builds; proving a change helped is `ai-evaluation`'s job,
+and no design below is "done" until it has an eval harness.
+
+## Workflow
+
+### Step 1: Choose the Simplest Sufficient Architecture
+
+Escalate only when the previous rung measurably fails:
+
+1. **Single prompt** — the task fits in one call with instructions + input.
+2. **+ RAG** — the answer needs knowledge that doesn't fit in the prompt or
+   changes independently of deploys.
+3. **+ Tools** — the model must act (query, search, write) — not just answer.
+4. **Agent loop** — the path to the goal is genuinely unpredictable in advance.
+   Most "agents" that fail are workflows that should have been a fixed pipeline
+   with one or two LLM steps.
+
+### Step 2: Engineer the Prompt as an Interface
+
+- Structure: role and constraints → domain context → task → output format.
+  Put stable content first (prompt caching) and the volatile input last.
+- State what to do on failure: "if the context doesn't contain the answer, say
+  so" — the unhappy path is where LLM apps lose user trust.
+- Version prompts in git like code; a prompt change is a deploy and goes
+  through the same eval gate (`ai-evaluation`).
+
+### Step 3: RAG — Design Retrieval Before Generation
+
+Most bad RAG answers are retrieval failures wearing a generation costume.
+
+- **Chunking**: split on document structure (headings, sections, one
+  ticket+resolution per chunk), not fixed character counts; attach metadata
+  (source, date, product area) for filtering and citations.
+- **Retrieval**: hybrid (BM25 + vector) as the default — pure vector search
+  misses exact identifiers, SKUs, and error codes; filter by metadata, then
+  **rerank** the candidate set (retrieve ~20–50, keep the top 5–10).
+- **Context budget** (decide, don't default): how many chunks fit, in what
+  order (most relevant near the question), the relevance floor below which a
+  chunk is dropped, and the behavior when nothing clears it — say "I don't
+  know" rather than pad the context with noise.
+- **Grounding prompt**: answer only from the provided context, cite which
+  source supports each claim, refuse when unsupported.
+
+### Step 4: Agents — Design the Tool Surface and the Loop
+
+- **Tools**: few and sharply distinct beat many and overlapping — every tool
+  description competes for the model's attention on every step. Name by
+  intent (`search_orders`, not `api_call`); make each tool's failure return a
+  message the model can act on, not a stack trace.
+- **Decomposition**: long tasks fail as one monolithic loop with 25 tools;
+  split into phases or sub-agents, each with a scoped toolset, and pass
+  structured summaries between them — not raw transcripts.
+- **Guardrails**: cap iterations, budget tokens per task, and validate
+  side-effecting tool calls (or require confirmation) — an agent retrying a
+  failed write in a loop is the classic production incident.
+
+### Step 5: Memory — Externalize State
+
+The context window is a scarce cache, not a database. For long-horizon work:
+keep a plan/scratchpad file the agent re-reads and updates; summarize or
+compact stale history instead of letting it scroll off; store durable facts
+(user preferences, decisions) outside the window and retrieve them like RAG.
+
+### Step 6: Wire In Evaluation Before Shipping
+
+Hand the design to `ai-evaluation`: a golden dataset (including unanswerable
+and adversarial cases), RAG-stage metrics (retrieval vs generation scored
+separately), agent task-success rate, and a CI regression gate. "The answers
+feel better" is not evidence; a design without an eval harness is a prototype.
+
+Deeper pattern detail (chunking table, reranking, memory patterns, failure
+modes): [references/patterns.md](references/patterns.md).
+
+## Principles Applied
+
+- **KISS**: every architecture rung you skip is a class of failure you never
+  have to debug. Workflows beat agents when the path is predictable.
+- **YAGNI**: no vector DB before checking whether the corpus fits in the
+  prompt; no agent framework before a plain loop with 3 tools fails.
+- **SRP for tools**: one tool, one capability — overlapping tools force the
+  model to guess, and it will guess differently each run.
+
+## Cross-Skill References
+
+- `ai-evaluation` — golden datasets, RAG metrics, judges, eval gates (the
+  measurement half of every step above)
+- `ml-model-deployment` — serving, monitoring, and drift once the app ships
+- `api-design` — the contract around the LLM feature (streaming, errors, timeouts)
+- `security-audit` — prompt injection, data exfiltration via tools, output handling
+- `architecture-design` — ADRs for costly-to-reverse choices (vector store, framework)