janderscience-skills 0.0.0-stage → 1.0.0

package/sources/headcount/plugins/technology/skills/implementation-planning/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: implementation-planning
+description: Turns a spec or requirement into a written plan a separate session or agent can execute, then drives that plan through review checkpoints. Use this before touching code on any multi-step task, when work needs handing to someone else, when a task keeps sprawling mid-implementation, or when a plan exists and needs executing in order with verification between steps.
+---
+
+# Implementation planning
+
+## When a plan is worth writing
+
+More than about three steps, more than one file of consequence, or any work that will be handed off.
+Below that, planning costs more than it saves.
+
+## Writing the plan
+
+A plan is executable when someone who was not in the conversation can follow it without guessing.
+That means every step names:
+
+- **The change** — the file or surface, and what it should do afterward.
+- **The proof** — the command that shows it worked. "Run the tests" is not a step; the exact
+  invocation is.
+- **The checkpoint** — whether a human reviews before the next step starts.
+
+Order steps so the system is working at the end of each one. A plan whose midpoint is a broken build
+cannot be paused, and every plan gets paused.
+
+State up front what is **out of scope**. Plans fail by accretion far more often than by being wrong.
+
+## Executing
+
+- One step at a time, in order. Finish and verify before starting the next.
+- **Stop at checkpoints.** The point of a checkpoint is that continuing without it is a mistake.
+- When reality contradicts the plan, stop and amend the plan. Do not improvise past it silently —
+  the plan is the shared state, and a stale plan is worse than none.
+- Track status *in* the plan as you go, so an interrupted run can resume.
+
+## Never
+
+- Start writing code because the plan felt obvious. If it was obvious, writing it costs a minute.
+- Mark a step done without running its proof.
+- Expand scope mid-execution. Note it, finish the plan, then decide.

package/sources/headcount/plugins/technology/skills/observability-and-reliability/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: observability-and-reliability
+description: Makes systems debuggable and reliably operable — instrumentation, alerting that is worth waking for, service objectives, and learning from failure. Use this to instrument a service, fix alerting that is ignored, set error budgets or reliability targets, prepare for on-call, or run a blameless post-incident review.
+---
+
+# Observability and reliability
+
+Monitoring tells you a thing you predicted is happening. Observability lets you ask a question you
+did not anticipate. Production failures are mostly the unanticipated kind.
+
+## Instrument for questions you have not thought of yet
+
+Emit structured events with enough context to slice afterwards — request identifiers, user or tenant,
+version, dependency, outcome, duration. Free-text logs are unsearchable at volume and become
+expensive noise.
+
+Propagate a correlation identifier across every hop. Without it, a distributed system is a set of
+independent stories and reconstructing one request is manual archaeology.
+
+Measure what the user experiences at the percentile they experience it. A p50 latency graph is
+mostly a graph of the people who were not affected.
+
+## Alert on symptoms, not causes
+
+Alert when users are affected or imminently will be. High CPU is not an alert; requests failing or
+slowing is. Cause-based alerting produces pages for conditions the system handled and no page for
+novel failures that hurt.
+
+Every alert must be **actionable, urgent and specific**. If the recipient's honest response is to
+look and close it, delete the alert — it is training the on-call to ignore the page, and the ignored
+page is eventually the real one.
+
+Alert fatigue is the actual reliability risk in most organizations. Fewer, better alerts beat
+coverage.
+
+## Objectives and error budgets
+
+Set service level objectives from what users need, then treat the remainder as a budget to spend.
+This converts a sterile argument between shipping and stability into arithmetic: budget remaining
+means ship, budget exhausted means the next work is reliability.
+
+Keep the internal objective tighter than any external commitment made through
+`operations:service-level-management`, so you find out before the customer does.
+
+## Learn from incidents
+
+Post-incident review exists to find what made the failure possible and hard to detect, not who
+touched it last. Human error is a starting question, never the finding: what made the error easy,
+and why did nothing catch it?
+
+Track the time to *detect* separately from time to resolve. Long detection is an observability
+defect, and it is the part that repeats.
+
+Produce a small number of real actions with owners and dates. A review generating fifteen actions
+generates none.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Tooling
+
+Metrics and traces: Datadog, Grafana with Prometheus, New Relic, Honeycomb, and similar.
+Errors: Sentry, Rollbar, and similar. Logs: Elastic, OpenSearch, Loki, Splunk, and similar.
+
+On-call and incident management: PagerDuty, Opsgenie, incident.io, FireHydrant, and similar.
+
+Instrument with OpenTelemetry wherever you can. Vendor-specific instrumentation is the part
+that makes leaving expensive.
+
+## Never
+
+- Page a human for something they cannot act on.
+- Alert on a cause when you can alert on the symptom.
+- Report reliability as an average when users experience the tail.
+- Close an incident review with the finding that someone was careless.

package/sources/headcount/plugins/technology/skills/observability-and-reliability/references/sources.md

@@ -0,0 +1,37 @@
+# Sources — `technology:observability-and-reliability`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## OpenTelemetry specification and semantic conventions
+
+OpenTelemetry project, Cloud Native Computing Foundation · global · CC BY — quote with attribution
+
+<https://opentelemetry.io/docs/specs/otel/>
+
+Machine-readable: <https://opentelemetry.io/docs/specs/semconv/>
+
+**Authoritative for:** The data model for traces, metrics and logs, and — in the semantic conventions — the attribute names themselves, which is what naming arguments actually turn on.
+
+## Site Reliability Engineering and The SRE Workbook
+
+Google · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://sre.google/sre-book/table-of-contents/>
+
+Machine-readable: <https://sre.google/workbook/table-of-contents/>
+
+**Authoritative for:** The definitions the reliability vocabulary rests on — indicator against objective against agreement, error budget, toil. It settles what the words mean, not whether a practice suits your organization.
+
+## Trace Context
+
+World Wide Web Consortium · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://www.w3.org/TR/trace-context/>
+
+**Authoritative for:** The on-the-wire format of the traceparent and tracestate headers, which settles how trace context propagates between tools from different vendors.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/technology/skills/parallel-agent-delivery/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: parallel-agent-delivery
+description: Splits work across multiple agents or sessions running at once, keeping their surfaces disjoint so results merge cleanly. Use this when facing several independent tasks with no shared state, when a plan has parallelizable steps, when a broad search or audit would be faster fanned out, or when deciding whether work can safely be split at all.
+---
+
+# Parallel agent delivery
+
+Parallelism is a property of the work, not a preference. Establish it before dispatching.
+
+## When it is safe
+
+All three must hold:
+
+1. **Disjoint write surfaces** — no two agents touch the same file. Not "unlikely to conflict";
+   provably disjoint.
+2. **No sequential dependency** — none needs another's output to start.
+3. **Independently verifiable** — each result can be judged on its own.
+
+Fail any one and run sequentially. Two agents editing one file produces a merge conflict at best and
+a silent lost update at worst.
+
+## Dispatching
+
+Each agent gets a self-contained brief: the goal, its exclusive surface, the context it cannot see
+for itself, and the shape of the answer expected. Agents share no memory — anything you leave out is
+gone.
+
+Ask for a **structured return**, the same shape from each, so results can be compared rather than
+re-read.
+
+## Read-only fan-out is the easy case
+
+Searching, auditing, and reviewing have no write surface at all, so they parallelize without risk.
+Reach for parallelism here first and freely.
+
+## Integrating
+
+- Review each result against its brief before merging any of them.
+- Where two disagree on a shared fact, neither is authoritative — resolve it yourself.
+- One agent returning nothing useful is a normal outcome, not a failure to retry blindly.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Split work to look faster when the steps are actually sequential.
+- Let two agents write to one surface because "they probably won't collide."
+- Merge a result you have not read.

package/sources/headcount/plugins/technology/skills/parallel-agent-delivery/references/sources.md

@@ -0,0 +1,17 @@
+# Sources — `technology:parallel-agent-delivery`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## Git reference manual
+
+Git project · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://git-scm.com/docs>
+
+**Authoritative for:** What a Git operation actually does — what a worktree is, what rebase rewrites, what detached HEAD means. It settles behavior, not which workflow a team should adopt.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/technology/skills/prompt-optimizer/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: prompt-optimizer
+description: Turns rough intent or a weak prompt into a reliable one — diagnosing why output is inconsistent, restructuring the instruction, and adapting it across models. Use this when a prompt is not producing what was wanted, when output varies run to run, when writing a prompt for a repeated task, when moving a prompt between models, or when someone describes what they want an AI to do and needs it written properly.
+---
+
+# Prompt optimizer
+
+## Diagnose before rewriting
+
+Bad output has a small number of causes, and the fix differs entirely by cause:
+
+- **Underspecified** — the model is guessing at something you know. Most common by far.
+- **Overspecified** — so many constraints that they conflict, and the model satisfies some
+  arbitrarily.
+- **Wrong shape** — asking for a paragraph when you want a table, or a decision when you want
+  options.
+- **No success criterion** — nothing in the prompt says what good looks like, so quality varies with
+  nothing.
+- **Buried instruction** — the actual task is in the middle of context and gets weighted like
+  context.
+- **Genuinely hard** — the task needs information the model does not have, and no prompt fixes that.
+  Say so rather than iterating.
+
+Read the actual bad output before rewriting. The failure mode names the cause.
+
+## What reliably helps
+
+- **Say what to do, not what to avoid.** Negative instructions are weaker than positive ones and
+  often summon the thing named.
+- **Give the shape of the output** — the sections, the length, the format. If format matters, show
+  an example rather than describing it.
+- **Provide one worked example** where the task is judgment-heavy. Examples carry more instruction
+  per token than description does, and one good one beats three mediocre.
+- **State the audience and purpose.** "For a technical reader deciding whether to adopt this" changes
+  the output more than most adjectives.
+- **Ask for reasoning before the answer** on analytical tasks — order matters, since a conclusion
+  stated first is defended rather than derived.
+- **Give an out.** Tell it what to do when the input is insufficient, or it will invent something.
+
+## What does not help
+
+Politeness, threats, incentives, insisting on importance, and stacked superlatives. These consume
+tokens and change little. So does repeating an instruction in three phrasings — it usually signals
+the instruction is unclear rather than reinforcing it.
+
+## Structure
+
+Put the task first, context second, and any output format last where it will be closest to
+generation. Long context between instruction and output is where instructions get lost.
+
+For repeated prompts, separate the fixed instruction from the variable input explicitly, so the
+model can tell which is which.
+
+## Testing
+
+A prompt is not done because one run looked good. Run it three to five times on the same input and
+look at the variance — that is the actual quality. Then run it on the awkward inputs: empty, far too
+long, ambiguous, adversarial.
+
+Fix the worst case, not the average. The average is what you see in testing; the worst case is what
+your users see.
+
+## Producing variations
+
+When a prompt matters enough to optimize, produce genuinely different versions rather than variants
+of one phrasing:
+
+- **Terse** — instruction only, minimal framing. Often outperforms, and it is cheapest.
+- **Structured** — explicit sections, numbered constraints, defined output shape.
+- **Exemplar-led** — one worked example carrying most of the instruction.
+- **Role-framed** — audience and stance set before the task.
+
+Test all four on the same inputs. Which wins is genuinely hard to predict, and the intuition that a
+longer prompt is better is wrong about as often as it is right.
+
+## Scoring output
+
+Judge against criteria written before seeing results, or you will rationalize whatever came back.
+For most tasks: did it do the task, is it correct, is it the right shape and length, is it usable
+without editing. Score each run rather than forming an overall impression — impressions are
+dominated by the best run, and the worst run is what matters.
+
+## Moving between models
+
+Do not assume a prompt transfers. Models differ in how they weight system versus user instruction,
+how they handle long context, and how they respond to formatting. Re-test on the target model, and
+be especially suspicious of prompts tuned through many small iterations — those are often fitted to
+one model's quirks.
+
+## Never
+
+- Rewrite a prompt before reading the failing outputs. You will fix the wrong thing.
+- Change more than one thing between test runs.
+- Judge a change on a single output. Sampling variance will fool you.
+- Keep an instruction because it was already there. Every line has to earn its tokens.

package/sources/headcount/plugins/technology/skills/release-and-deployment/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: release-and-deployment
+description: Ships changes safely and often — pipelines, deployment strategies, feature flags, rollback, and database changes. Use this to design a deployment pipeline, reduce release risk, roll out a risky change gradually, plan a schema migration, or work out why releases are infrequent and frightening.
+---
+
+# Release and deployment
+
+Release risk is dominated by batch size. Large infrequent releases are dangerous because many changes
+land at once and nobody can tell which one broke it — so teams release less often, which makes each
+release larger. The loop is the problem.
+
+## Separate deploy from release
+
+Deploying code and exposing behavior to users are different acts, and coupling them forces every
+deployment to be a business decision.
+
+Decouple with flags: deploy continuously, expose deliberately. This makes rollback a configuration
+change rather than a redeployment, which is the difference between seconds and minutes at the worst
+possible time.
+
+Flags are inventory and rot. Give each an owner and a removal date; a codebase full of stale flags
+has combinatorial states nobody has tested.
+
+## The pipeline is the quality gate
+
+Automate everything between commit and production, and let the pipeline reject. Manual steps get
+skipped under pressure, which is exactly when they matter.
+
+Order gates fast-to-slow so failure is cheap: lint and unit tests, then integration, then anything
+requiring a deployed environment. A pipeline slow enough to be circumvented is worse than a fast one
+with fewer checks, because it will be circumvented.
+
+Build once and promote the same artifact through environments. Rebuilding per environment means the
+thing you tested is not the thing you shipped.
+
+## Roll out gradually
+
+Expose to a small population first and watch real signals before widening. Canary or percentage
+rollout turns a total failure into a contained one.
+
+Define the abort condition **before** starting, with a threshold and a named decision-maker. Under
+pressure, and with the change fresh, the instinct is always to wait a little longer and see.
+
+## Database changes are the asymmetric risk
+
+Code rolls back; data does not. Make schema changes backward-compatible and multi-step: add the new
+structure, write to both, migrate, switch reads, then remove the old — with the application tolerant
+of both shapes throughout.
+
+Test the migration against production-scale data. A migration that is instant on a development
+dataset can lock a large table for a length of time nobody modeled.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Tooling
+
+Pipelines: GitHub Actions, GitLab CI, CircleCI, Buildkite, Jenkins, and similar.
+
+Continuous delivery and progressive rollout: Argo CD, Flux, Spinnaker, and similar; feature flags
+for decoupling deploy from release — LaunchDarkly, Unleash, Split, and similar.
+
+Schema migrations: Flyway, Liquibase, Alembic, and similar. Whichever you use, the property that
+matters is that migrations are versioned, ordered, and applied by the pipeline rather than by a
+person with a database client.
+
+## Never
+
+- Couple deploying code to exposing behavior.
+- Promote a different artifact than the one that was tested.
+- Begin a rollout without a defined abort condition.
+- Ship a schema change that requires the application and database to deploy simultaneously.

package/sources/headcount/plugins/technology/skills/release-and-deployment/references/sources.md

@@ -0,0 +1,19 @@
+# Sources — `technology:release-and-deployment`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## SPDX License List
+
+The Linux Foundation · global · CC BY — quote with attribution
+
+<https://spdx.org/licenses/>
+
+Machine-readable: <https://github.com/spdx/license-list-data>
+
+**Authoritative for:** The canonical identifier and full text of every common open-source license — the reference for an inbound license review, and for what a share-alike obligation actually says.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/technology/skills/skill-authoring/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: skill-authoring
+description: Writes and revises agent skills so they trigger at the right moments and give usable instruction when they do. Use this when creating a new skill, editing an existing one, diagnosing a skill that fires too often or never fires, or reviewing a set of skills for overlap. Also use before adding to a skill library, to check the capability is not already covered.
+---
+
+# Skill authoring
+
+A skill is judged twice: on whether it loads at the right moment, and on whether it helps once
+loaded. Most fail the first test.
+
+## The description does the triggering
+
+It is the only part read when deciding whether to load. Write it for that job:
+
+- Lead with **what the skill does**, in one clause.
+- Then **when to reach for it** — the situations, in the words someone would actually use, including
+  the oblique ones ("why isn't this converting" as well as "CRO audit").
+- Name the **edge cases that should still trigger it**, and where useful, what should *not*.
+
+Vague descriptions produce two failures at once: the skill misses cases it should catch, and fires
+on cases it cannot help.
+
+## The body does the work
+
+Write for someone competent who has not thought about this problem today. That means:
+
+- **Method over exhortation.** "Be thorough" is noise. An ordered procedure is instruction.
+- **State the failure behind each rule.** A rule with no failure attached gets optimized away by the
+  next reader.
+- **Be specific enough to be wrong.** Guidance too hedged to contradict is too vague to follow.
+- **Put long material in `references/`** and say when to read it. The body should fit in working
+  memory.
+
+## Overlap is the silent killer
+
+Two skills whose descriptions both match a request means neither reliably wins. Before adding one,
+check what already covers the ground. Prefer extending an existing skill, or consolidating the
+family into one skill with references, over adding a near-neighbor.
+
+## Mechanics
+
+- `name` must be lowercase-hyphenated and equal the directory name, or the skill will not load.
+- One skill, one directory, `SKILL.md` at its root; supporting material in `references/` and
+  `scripts/`.
+
+## Verify before shipping
+
+Write three requests that should trigger it and two that should not, and check the description
+actually discriminates. If a near-miss request would pull it in, tighten the description.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Ship a skill whose description does not say when to use it. A skill that never triggers is dead weight.
+- Write a skill that restates what the model already does well without prompting.
+- Let two skills claim the same trigger. Move the boundary or merge them.
+- Ship without running the skill against the case that motivated writing it.

package/sources/headcount/plugins/technology/skills/skill-authoring/references/sources.md

@@ -0,0 +1,17 @@
+# Sources — `technology:skill-authoring`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## Agent Skills documentation
+
+Anthropic · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview>
+
+**Authoritative for:** The SKILL.md format and its loading semantics — required frontmatter, body, and how bundled resources are surfaced. The format, not what makes a skill good.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/technology/skills/solution-architecture/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: solution-architecture
+description: Designs system structure and makes architectural decisions defensible — boundaries, coupling, trade-offs, and recording why. Use this to design a new system or major component, choose between architectural options, review an existing design, decide where a boundary belongs, or document an architectural decision so it survives the people who made it.
+---
+
+# Solution architecture
+
+Architecture is the set of decisions that are expensive to reverse. Everything cheap to change later
+is design, and does not need this level of ceremony.
+
+## Start from what constrains, not from what appeals
+
+Architecture is driven by quality attributes, not by features. Establish the ones that actually bind
+before drawing anything: expected load and its shape, latency the user notices, availability the
+business will fund, data residency and retention obligations, the rate of change the team needs to
+sustain, and the size and skills of the team who will operate it.
+
+Vague attributes produce vague architecture. "Scalable" is not a requirement; "20,000 concurrent
+sessions with p99 under 300ms" is a constraint that eliminates options.
+
+## Boundaries are the whole game
+
+Draw boundaries where change is independent and where data has a single owner. A boundary in the
+right place absorbs change; a boundary in the wrong place turns every feature into a negotiation
+across three teams.
+
+The reliable test: if a routine change requires coordinated deployment across two components, the
+boundary is wrong regardless of how clean the diagram looks.
+
+Prefer coarse boundaries until you have evidence for finer ones. Distributed systems convert simple
+in-process failures into network, partial-failure and consistency problems — a cost worth paying for
+independent scaling or independent deployment, and not worth paying for tidiness.
+
+## Trade-offs, stated
+
+Every architecture sacrifices something. The failure is not choosing badly; it is choosing without
+naming what was given up, so nobody later understands why the constraint exists.
+
+Present options with their costs: what each makes easy, what each makes hard, what it costs to
+operate, and what it would take to reverse. Two credible options and an honest comparison beat one
+recommendation.
+
+## Record decisions
+
+Write down the decision, the context at the time, the options considered, and the consequences
+accepted. Architecture rots because the reasoning evaporates while the structure remains, and the
+next team reads a constraint as an accident.
+
+Keep records short and immutable — supersede rather than edit, so the history of thinking survives.
+
+## Sources
+
+`references/sources.md` in this skill lists the outside authorities that settle the questions
+here — what each one is authoritative for, and what you may do with it. Check them before
+answering on anything they cover, and cite what you used. Most are free to read and not free
+to reproduce; the use note on each is binding.
+
+## Never
+
+- Design against quality attributes nobody has quantified.
+- Split a system into services to make the diagram tidy.
+- Present a single option as though no trade-off was made.
+- Leave an expensive-to-reverse decision undocumented.

package/sources/headcount/plugins/technology/skills/solution-architecture/references/sources.md

@@ -0,0 +1,17 @@
+# Sources — `technology:solution-architecture`
+
+<!-- Generated by scripts/build-sources.py from sources/*.toml. Do not edit. -->
+
+Check these before answering on anything they cover, and cite what you used. The use note on each one is binding: most of what a professional cites is free to read and not free to reproduce.
+
+## AWS Well-Architected Framework
+
+Amazon Web Services · global · **read and cite only — copyrighted, do not reproduce**
+
+<https://docs.aws.amazon.com/wellarchitected/latest/framework/welcome.html>
+
+**Authoritative for:** What AWS itself considers a correct design on AWS, and therefore what an AWS architecture review will be graded against.
+
+---
+
+Sources are maintained in `sources/` upstream, not here. If one is wrong, out of date, or missing, fix it there — this file is regenerated and an edit to it is lost.

package/sources/headcount/plugins/technology/skills/solution-exploration/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: solution-exploration
+description: Explores the problem and the range of possible approaches before any code is written — clarifying what is actually being asked, surfacing options with their tradeoffs, and converging on one. Use this at the start of any feature, component, or behavior change, when a request is ambiguous, when the first idea is the only idea on the table, or when a design decision needs pressure-testing before commitment.
+---
+
+# Solution exploration
+
+The most expensive bugs are decisions, not defects. This runs before implementation, not instead of
+it.
+
+## Establish what is actually wanted
+
+The stated request is a proposed solution wearing the clothes of a requirement. Get underneath it:
+
+- What outcome does the person want? What breaks today without it?
+- Who else touches this, and what do they assume about it now?
+- What is explicitly **not** being asked for?
+- How will we know it worked — the observable difference.
+
+If the answers conflict, stop and resolve that first. Building the average of two requirements
+satisfies neither.
+
+## Generate genuinely different options
+
+Two variations of the same idea are one option. Force real range:
+
+- The smallest thing that could work.
+- The version that assumes this doubles in scope next quarter.
+- The version that requires no new moving parts.
+- Buy, borrow, or do nothing.
+
+For each: what it costs, what it forecloses, and what has to be true for it to be right.
+
+## Converge
+
+Recommend one and say why the others lost. A comparison that ends without a recommendation has
+moved the work, not done it.
+
+Name the assumption the recommendation rests on most heavily — that is where the plan will break if
+it breaks.
+
+## Never
+
+- Present options you would not accept as padding around the one you want.
+- Skip this because the task "is simple." Simple tasks take five minutes here.
+- Let a preference stand in for a reason.