@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/core/house-style/templates/brd.md

@@ -0,0 +1,103 @@
+# BRD: business requirements
+
+## Use when
+
+The reader is business sponsors, product managers and technical leads who must agree on why a
+change is worth making, what it must achieve, and which business processes it changes. They use
+the BRD to approve the case and set scope before anyone designs product behavior or a system.
+
+- Pick **prd** instead when the question is what users experience: states, eligibility, entry and
+  return, notifications, failures and acceptance scenarios.
+- Pick **technical-spec** for how it is built: architecture, schemas, APIs, performance targets.
+- Pick **gap-analysis** when the work is measuring today against a fixed baseline, not proposing a
+  change.
+When a BRD and a PRD both exist, cross-reference them; never copy one into the other.
+
+## Tone
+
+Concise, unambiguous business language, low technical depth. Bullets and sourced numbers over
+paragraphs and adjectives. No marketing words ("innovative", "seamless", "world-class").
+
+## Inputs
+
+- The driver: a problem, an opportunity or a strategic decision, with who raised it. Material: ask
+  once if the brief gives no reason for the change.
+- Primary users and the business processes they run. Material: ask once.
+- Business data: volumes, costs, revenue, rates, durations, targets. Use each figure exactly with
+  its source. Missing → `[TBD: <figure>, owner: <who holds the data>]`; never estimate one.
+- Constraints: regulation, contracts, dependencies on other teams or vendors, deadlines.
+- Decisions already taken, and by whom.
+
+Without baseline data, describe the target process directly. Do not write a current-versus-future
+comparison or an improvement percentage.
+
+## Reasoning
+
+WHY before WHAT; never HOW.
+
+1. State the driver and its business impact in two or three sentences, sourced.
+2. Turn the driver into objectives: outcomes the business can recognize, not features.
+3. Name the primary users and what each needs from the change.
+4. Map each major process from trigger to outcome, including exception paths and decision points
+   with business criteria. Draw one Mermaid flowchart per major process.
+5. Embed requirements in the process they serve. Give each a priority and a business reason:
+   - **P0**: the business cannot operate or comply without it.
+   - **P1**: important to the value case; planned for the first release.
+   - **P2**: adds value; can move to a later phase.
+6. Where two or more approaches are viable, compare them on five dimensions: user value, user
+   experience, user cost, our cost, strategic fit. Recommend one and state the trade-off accepted.
+7. List every question still open with an owner and the impact if it stays open.
+
+Then test the boundary. Example: "Approval routes to a manager above `[TBD: threshold, owner: <who
+sets approval limits>]`" is a business rule and stays. "Approvals are stored in an `approvals` table with a
+status enum" is implementation and goes. "The approve button greys out after one click" is PRD.
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **Executive summary** (Required): background, objective and business value, one or two
+   sentences each. A sponsor can approve or reject from this alone.
+2. **Business context** (Required): driver type (problem / opportunity / strategic), the
+   situation, objectives (primary and secondary), constraints and dependencies.
+3. **Users** (Required): primary users only, as a table: user type, who they are, key needs, pain
+   points. Secondary audiences belong in the PRD.
+4. **Business processes and requirements** (Required): one subsection per process with a short
+   description, its Mermaid flowchart, then its requirements, each with priority, business value
+   and description. Example: "**R2.1 Same-day refund approval** (P1). Business value: support
+   reports refund queries as the top contact reason `[source]`. Refunds under the auto-approve
+   limit complete without an agent."
+5. **Open questions** (Required): question, impact if unresolved, and owner and target date when
+   known.
+6. **Scope** (Optional): in-scope modules described in a sentence or two each, out-of-scope items,
+   phase boundaries. A full feature checklist goes in an appendix, not here.
+7. **Business rules** (Optional): complex logic or regulatory constraints, stated once, each with
+   its source. Process sections refer to them.
+8. **Success metrics** (Optional): only when a baseline exists and stakeholders agree how to
+   measure. Table: metric, current, target, timeline, method; every figure sourced.
+9. **Non-functional requirements** (Optional): only regulatory compliance (cite the instrument and
+   article) or business continuity (critical hours, cost of disruption). Never latency, uptime
+   percentages, code quality or infrastructure.
+10. **Solution options** (Optional): for a decision that spans processes. The five-dimension
+    comparison, the recommendation, and trade-offs accepted. Qualitative unless data is given.
+11. **Implementation strategy** (Optional): phases with focus and key deliverables, and the
+    trigger for starting each later phase. Not a project plan.
+12. **Approval** (Optional): approvers, role and date, when governance requires sign-off.
+
+## Done when
+
+- Does the business context explain why before any requirement says what?
+- Does every requirement carry P0, P1 or P2 with a business reason?
+- Does every major process have a flowchart that includes at least one exception path?
+- Is every number sourced, or marked `[TBD]` with an owner?
+- Is there no current-versus-future comparison unless baseline data was supplied?
+- Does every open question state its impact, with owner and date where known?
+- Are user stories, UI states, schemas, APIs, architecture and technical performance absent or
+  linked out to the PRD or technical spec?
+- Does each solution comparison end in one recommendation with its trade-off stated?
+
+## Sources
+
+Adapted from the retired `brd` skill in this repository (1aboveio/ai, MIT): its WHY/WHAT focus,
+mandatory components, optional modules, priority scheme, five-dimension option analysis and
+anti-patterns. See [sources](../references/sources.md).

package/skills/core/house-style/templates/commercial-proposal.md

@@ -0,0 +1,93 @@
+# Commercial proposal: client offer
+
+## Use when
+
+The reader is the client decision-maker who approves the deal, their procurement and finance
+team who check scope, price and terms, and often a technical evaluator who checks the approach.
+They use the proposal to decide whether to buy, and on what terms. It covers a consulting
+engagement, a software or platform deal, or a services contract.
+
+- Pick **brd** instead for an internal business case for our own change.
+- Pick **gap-analysis** when the deliverable is the assessment itself, not an offer to fix it.
+  A gap analysis can be an input that shapes the proposal's approach.
+- Pick **integration-guide** or **technical-spec** for technical detail after the deal; link
+  them from the proposal rather than embedding them.
+
+## Tone
+
+Confident, client-centered, formal. Low to medium technical depth; the technical evaluator gets
+detail in an appendix, not in the summary.
+
+## Inputs
+
+- Discovery notes: the client's situation, problem, goals and constraints, in their words.
+  Material: ask once; do not invent the client's problem.
+- Scope, deliverables, team and timeline from the brief.
+- Prices, rates, discounts, payment terms, validity period and dates. Material: mark [TBD].
+  They come only from the brief; never from examples, templates or prior proposals.
+- Evidence for every capability claim: case studies, references, certifications, team
+  experience. Use only real, supplied evidence; no evidence → drop the claim or mark it `[TBD]`.
+- Legal and contractual terms supplied by the user. Copy them as locked text.
+
+## Reasoning
+
+Argue from the client's need to our offer, and bound every promise:
+
+1. Restate their situation and problem in their words, from discovery.
+2. Turn it into outcomes and success criteria they would sign.
+3. Present our approach and tie each element to a stated need. An element with no need behind it
+   is padding; cut it or name the need.
+4. Fix the scope: deliverables, in scope, out of scope, assumptions, client dependencies.
+   Assumptions bound the price, so state each one. Example: "Assumes the client provides test
+   accounts within five business days of kickoff; delay moves the timeline, not the fee."
+5. Plan, team and commercials follow from that scope. Say what changes the price.
+6. Name the risks to the outcome and how each is handled, including the client's part.
+7. Prove fit with evidence, then make the next step easy.
+
+Keep contractual commitments and indicative statements visibly apart. Example: "Fixed fee:
+`[TBD: fixed fee, owner: <deal owner>]`" is a commitment; "Typical clients see results within a quarter" is
+indicative and needs a source or must go.
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings. Open items go in the
+delivery note to the author, never into the client-facing text.
+
+1. **Executive summary** (Required): the client's problem, the outcome offered, the price, the
+   timeline and the decision asked. The decision-maker can approve from this page alone.
+2. **Your situation** (Required): the problem and context in the client's words.
+3. **Outcomes and success criteria** (Required): what will be true at the end, and how both
+   sides will measure it.
+4. **Our approach** (Required): the method, phases and why it fits, each element linked to a
+   stated need.
+5. **Scope** (Required): deliverables; in scope; out of scope; assumptions; client
+   dependencies. A table works well here.
+6. **Plan and team** (Required): phases, milestones, dates and the named roles. Dates only from
+   the brief.
+7. **Commercials** (Required): pricing model, price table, payment terms, validity period, and
+   what changes the price. Mark each line contractual or indicative.
+8. **Risks and mitigations** (Required): each risk, how it is handled, and its owner when known.
+9. **Why us** (Optional): relevant experience and references, only real and supplied ones.
+10. **Next steps and acceptance** (Required): what the client does to proceed, by when, and the
+    signature or acceptance block.
+11. **Terms and appendices** (Optional): supplied legal terms as locked text, technical detail,
+    CVs, case studies.
+
+Supplied legal terms are [locked text](../references/rules.md#template-shape).
+
+## Done when
+
+- Can the decision-maker approve from the executive summary alone?
+- Is the client's problem stated in their words and traced to discovery?
+- Does every element of the approach link to a stated need?
+- Does every price, rate, discount and date come from the brief, with none from examples?
+- Are assumptions and client dependencies explicit, and is it clear what changes the price?
+- Is each statement clearly contractual or indicative?
+- Does every capability claim and reference rest on supplied evidence?
+- Are supplied legal terms copied verbatim in locked blocks?
+- Is the next step concrete, with a date or validity period?
+
+## Sources
+
+Authored for this skill; improve from approved examples via `distill-writing`. See
+[sources](../references/sources.md).

package/skills/core/house-style/templates/compliance-policy.md

@@ -0,0 +1,109 @@
+# Compliance policy: the firm's binding rules
+
+## Use when
+
+The firm needs its own binding rules for a regulated area, such as AML/CFT, sanctions, data
+protection, complaints handling or outsourcing. Three readers use it:
+
+- The board or senior management approve it and stay accountable for it.
+- Staff must follow it and need to find what applies to them.
+- Regulators and auditors test the firm against it and trace it back to the law.
+
+A policy says WHAT the firm requires and WHO is accountable. Step-by-step HOW belongs elsewhere.
+
+- Pick **risk-operations-procedure** for the steps an analyst follows to carry out a policy.
+- Pick **gap-analysis** to measure the firm against a regulation before or after writing the policy.
+- Pick **brd** when the question is a business change that compliance only constrains.
+
+## Tone
+
+Formal and normative. Short declarative statements, one obligation each. Define these words once
+and use them only in these meanings:
+
+- **must** / **must not**: mandatory; a breach is a policy breach.
+- **should**: expected; departing from it needs a recorded reason.
+- **may**: permitted, not required.
+
+## Inputs
+
+- The governing instruments, each with jurisdiction, version or effective date. Material: ask once if
+  the jurisdiction is unknown. Ask about the licence type only when an obligation depends on it.
+- A `reg-parser` checklist of each instrument, when one exists or `reg-parser` is installed: it
+  gives the obligations and paragraph citations for the regulatory basis.
+- The firm's licence, products, customer types and risk assessment, where the policy scales to risk.
+- The organization: roles that exist (board, compliance officer, MLRO, DPO, business owners), and
+  who approves policies.
+- Existing policies and procedures this one replaces or links to.
+- Regulator-mandated wording, if any. Copy it into a `locked` block, unchanged.
+
+Never invent a threshold, frequency or retention period. Use the instrument's figure with its
+citation, or mark it `[TBD: <figure>, owner: <policy owner>]`.
+
+## Reasoning
+
+1. **List the obligations.** Read each instrument and extract every obligation at paragraph level.
+   Cite instrument and paragraph. Example: "Instrument X, para 4.2: verify identity before
+   establishing a business relationship."
+2. **Turn each obligation into a policy statement** with must or must not. Where the firm goes
+   further than the law, say so. Example: "The firm must verify a customer's identity before it
+   opens an account or processes a first payment."
+3. **Assign accountability.** One accountable role per statement; responsible roles as needed.
+   Roles, not names. With no role named for a statement, the policy owner is accountable.
+4. **Set controls**: what control enforces each statement, its type (preventive, detective), its
+   frequency, and who performs it. Detail goes to the procedure; the policy names the control.
+5. **Define exceptions and breaches**: who may approve a departure, how it is recorded and for how
+   long; how a breach is reported, escalated and, where required, notified to the regulator.
+6. **Record governance**: owner, approver, review cycle, triggers for an early review; version
+   history when an earlier version exists.
+
+Then check coverage: every obligation (in the mapping table or cited inline) lands in a policy
+statement, and every
+policy statement traces to an obligation or a stated firm choice.
+
+Regulator- or scheme-mandated wording (a disclosure, a statement of responsibility) is
+[locked text](../references/rules.md#template-shape).
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **Purpose and scope** (Required): what risk the policy manages, which entities, products,
+   staff and third parties it covers, and what it does not cover.
+2. **Definitions** (Required): the normative words above and any defined term used later.
+3. **Regulatory basis** (Required): mapping table: obligation, source (instrument and paragraph),
+   policy section. In a short policy (under about ten statements), cite the source paragraph at the
+   end of each statement instead; no separate table.
+4. **Roles and responsibilities** (Required): table: role, accountable for, responsible for,
+   reports to. Board and senior-management duties appear here.
+5. **Policy statements** (Required): grouped by topic (for AML: risk assessment, due diligence,
+   monitoring, reporting, record keeping, training). Numbered statements, one obligation each.
+6. **Controls** (Required): the control per statement group, its frequency and performer, and a
+   link to the procedure that carries it out.
+7. **Exceptions, breaches and escalation** (Required): approval authority for exceptions, breach
+   reporting route and timelines, regulatory notification duties.
+8. **Training and awareness** (Optional): who must be trained, on what, how often.
+9. **Monitoring and assurance** (Optional): how compliance with the policy is tested, by whom
+   (second line, internal audit), and how often.
+10. **Governance** (Required): owner, approver, effective date, review cycle, early-review
+    triggers. A version history table only when an earlier version exists; a first draft states
+    "Version 1, pending approval" in one line.
+11. **Related documents** (Optional): procedures, other policies, the instruments. Never link to a
+    procedure that does not exist yet; mark it `[TBD]` with an owner.
+
+## Done when
+
+- Does every policy statement use must, must not, should or may in its defined sense?
+- Is every regulatory obligation in scope cited to its paragraph (mapping table, or inline in a
+  short policy)?
+- Does every policy statement have exactly one accountable role (the policy owner by default)?
+- Is step-by-step HOW absent, with a link to the procedure, or a `[TBD]` for one, instead?
+- Is every threshold, frequency and retention period cited or marked `[TBD]` with an owner?
+- Are exception approval and breach escalation routes named, with timelines where the law sets one?
+- Are owner, approver and review cycle stated, with version history only when an earlier version
+  exists?
+- Is any regulator-mandated wording reproduced verbatim in a `locked` block?
+
+## Sources
+
+Authored for this skill; improve from approved examples via `distill-writing`. See
+[sources](../references/sources.md).

package/skills/core/house-style/templates/gap-analysis.md

@@ -0,0 +1,105 @@
+# Gap analysis: current state against a baseline
+
+## Use when
+
+The reader is a function head, risk or compliance owner, or steering group who must know how far
+today's state falls short of a fixed baseline, and what to fix first. They use the document to
+accept the findings, fund the remediation and track it to closure.
+
+The baseline can be a regulation or scheme rule (compliance), a risk appetite or control framework
+(risk), a target process or SLA (operations), or a requirement set or market baseline (product).
+
+- Pick **compliance-policy** when the output is the firm's own rules, not an assessment against
+  someone else's.
+- Pick **brd** when the change is already decided and the question is what the business needs.
+- Pick **prd** when the gaps are agreed and the work is specifying the product behavior that
+  closes them.
+- Pick the `contract-compare` skill when the baseline and the subject are both contracts.
+- Pick the `compliance-audit` skill to run the audit itself against a checklist (tracker and
+  evidence); use this template to write up its result.
+- An audit report built from completed audit findings for a regulator or board belongs to the
+  `report-writing` skill, not this template.
+
+## Tone
+
+Neutral and evidential. Formal for compliance and risk, plainer for operations and product. Every
+judgment sits next to the evidence that supports it; no softening words ("largely", "broadly").
+
+## Inputs
+
+- The baseline: its name, version or effective date, and scope. Material: ask once if the version is
+  unclear; a gap against the wrong version is worthless.
+- A `reg-parser` checklist of the baseline instrument, when one exists or `reg-parser` is
+  installed: it gives the paragraph-level requirements, IDs and citations for Reasoning step 1.
+- Current-state evidence: documents, interviews, samples, system observations. Record for each
+  item what it is, its date and who provided it.
+- The severity scale. Use the firm's own if one is given; otherwise state the scale used in the
+  method section.
+- Owners and target dates for remediation. Missing → `TBD` in those table cells and one sentence
+  above the roadmap naming who will agree them. Never assign a person or a date nobody agreed.
+
+If evidence for part of the baseline cannot be obtained, narrow the scope and say so, or rate those
+requirements **Not assessed**.
+
+## Reasoning
+
+1. **Fix the baseline.** Break it into individual requirements at paragraph or clause level, each
+   with an ID and its citation. Example: "R-14 · Scheme rule 5.3.2(b): retain dispute evidence for
+   the stated period."
+2. **Describe the current state with evidence.** For each requirement, what exists today and how
+   you know. Grade evidence strength: **strong** (sample tested or system observed), **moderate**
+   (document reviewed), **weak** (interview or self-assessment only).
+3. **Rate each requirement**: **Met**, **Partial**, **Not met** or **Not assessed**. Never infer
+   Met without evidence. "No evidence seen" is Not assessed or a finding about evidence, not Not
+   met; say which. Example: "Policy requires dual approval (document). Sample of 25 showed 3 single
+   approvals (tested). Partial."
+4. **Rate severity** for every Partial and Not met on the stated scale, using the domain basis
+   below.
+5. **Find the root cause** where the evidence shows it: no rule, rule not followed, no tool, no
+   capacity, no ownership. Write "not established" rather than guess.
+6. **Set remediation**: one action per gap, with owner, target date and the evidence that will
+   prove closure.
+7. **Prioritize** into a roadmap by severity, dependency and effort. Group quick wins separately.
+
+| Domain | Typical baseline | Typical evidence | Severity basis |
+| --- | --- | --- | --- |
+| Compliance | Regulation, guideline, scheme rule | Policies, procedures, sample tests, records | Regulatory breach, sanction or licence exposure |
+| Risk | Risk appetite, control framework | Control tests, risk register, loss and incident data | Residual risk against appetite |
+| Operations | Target process, SLA, operating model | Process walk-throughs, volumes, queue and timing data | Customer harm, backlog, cost, SLA breach |
+| Product | Requirement set, competitor or market baseline | Product walkthrough, release notes, analytics | Lost deals, adoption, contractual commitment |
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **Summary** (Required): the baseline, the scope, counts by rating and severity, the top gaps
+   and the headline recommendation.
+2. **Scope and method** (Required): baseline and version, what is in and out, evidence types used,
+   the period covered, the rating definitions and the severity scale.
+3. **Requirement traceability** (Required): the core table, one row per requirement: ID,
+   requirement, source citation, current state, evidence and strength, rating, severity. Long
+   tables go in an appendix with a filtered view of gaps here.
+4. **Findings** (Required): one entry per Partial or Not met gap: what falls short, evidence,
+   impact, root cause, severity. Group related requirements under one finding when they share a
+   cause.
+5. **Remediation roadmap** (Required): action, gap IDs it closes, owner, target date, closure
+   evidence, priority or phase.
+6. **Not assessed** (Required when any exist): each requirement not assessed, why, and what
+   evidence would settle it.
+7. **Dependencies and assumptions** (Optional): anything the roadmap relies on.
+8. **Appendix** (Optional): full traceability table, evidence register, interview list.
+
+## Done when
+
+- Does every requirement cite its source down to the paragraph or clause?
+- Does every rating sit beside its evidence and that evidence's strength?
+- Is nothing rated Met without evidence, and is "no evidence seen" kept apart from "not met"?
+- Is the severity scale stated, and is every gap rated on it?
+- Does every gap have a remediation action with an owner and date, or `TBD` with the sentence
+  naming who will agree them?
+- Could a reviewer trace any summary count back to rows in the traceability table?
+
+## Sources
+
+Authored for this skill; improve from approved examples via `distill-writing`. See
+[sources](../references/sources.md).

package/skills/core/house-style/templates/general.md

@@ -0,0 +1,63 @@
+# General: an outline built for the assignment
+
+## Use when
+
+No project or bundled template fits: a memo, a briefing, a research summary, a project update, a
+one-off explainer. The reader and their decision come from the brief.
+
+- Check the other templates first. A document that compares a current state with a required one is
+  a **gap-analysis**; one that tells staff what they must do is a **compliance-policy** or a
+  **risk-operations-procedure**.
+
+## Tone
+
+From WRITING.md; otherwise the language guide ([English](../references/style-en.md),
+[中文](../references/style-zh.md)).
+
+## Inputs
+
+- The reader, and what they will decide or do after reading. Material: ask once if the brief does
+  not say and the sources do not show it.
+- The sources the brief names. Read them before outlining.
+
+## Reasoning
+
+Build the outline from the reader's question, not from a familiar shape:
+
+1. Write the reader's question in one sentence. Example: "Should we move dispute handling in-house
+   next quarter?"
+2. Write the answer in one or two sentences. This becomes the opening.
+3. List what the reader must believe to accept the answer. Each item becomes a section, ordered so
+   that each relies only on earlier ones.
+4. For each section, list the evidence that supports it. A section with no evidence becomes an open
+   question or is cut.
+5. Close with what happens next: the decision asked for, the actions and owners, or the open
+   questions.
+
+Pick the document's mode and keep it: **decide** (options against criteria, a recommendation),
+**inform** (status or findings, what changed, what it means), or **instruct** (steps to follow). Do
+not mix instruction steps into a decision memo.
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **Summary** (Required): the answer, and the decision or action asked of the reader.
+2. **Context** (Optional): only what the reader needs and does not already know.
+3. **Body sections** (Required): one per item from Reasoning step 3, each opening with its point.
+4. **Options** (Optional, decide mode): each option against the same named criteria, then the
+   recommendation and its consequences.
+5. **Next steps or open questions** (Required): owner and date for each, when known.
+6. **Sources** (Optional): what the facts came from, when the reader may check them.
+
+## Done when
+
+- Does the first paragraph give the answer, not the background?
+- Does every section support the answer, and could the reader say why each is there?
+- Is the mode (decide, inform, instruct) consistent throughout?
+- Does every next step or open question have an owner, or `TBD` (`待确认`, `待確認`) in its cell under the sentence
+  naming who will agree it?
+
+## Sources
+
+Authored for this skill. Save a recurring shape as a project template with `distill-writing`.

package/skills/core/house-style/templates/integration-guide.md

@@ -0,0 +1,98 @@
+# Integration guide: client developers
+
+## Use when
+
+The reader is a developer at a client or partner who integrates with our API, SDK or platform.
+They know their own stack, not ours, and have no internal knowledge. They want a first working
+call quickly, then a reference to build against, then help when something breaks.
+
+- Pick **technical-spec** instead for our own engineers designing or changing the system. The
+  spec may be a source for this guide; never copy its internal detail into it.
+- Pick **commercial-proposal** for the deal, pricing and scope; pick **prd** for product
+  behavior agreed internally.
+- Pick **general** for a short announcement of an API change; this template is the full guide.
+
+## Tone
+
+Direct, second person, task-focused. High technical depth about the public interface; zero
+internal vocabulary.
+
+## Inputs
+
+- The public API definition: endpoints, fields, enums, errors, webhooks, limits, versions. An
+  OpenAPI file or SDK source is best. Material: ask once; do not reconstruct an API
+  from memory or examples.
+- Sandbox and production details: base URLs, how credentials are issued, test data, differences.
+  Missing → `[TBD: sandbox base URL, owner: <who>]`.
+- Security requirements: key storage, signature scheme, IP allowlists, TLS.
+- The main client tasks (for a payment API: create a payment, refund, receive a webhook).
+- Go-live, versioning and support process. Use supplied values exactly.
+
+Treat internal docs and specs as sources to filter. Never publish internal system names, internal
+hostnames, admin endpoints or behavior the client is not meant to rely on.
+
+## Reasoning
+
+Order the guide by what the developer needs next, and keep four kinds of content apart:
+
+1. **Get started** (learning): the shortest path to one successful call, end to end, in sandbox.
+2. **How-to** (doing): one page per task. Each states the goal, the steps, and the expected
+   result the developer can check.
+3. **Reference** (looking up): complete, uniform, no narrative.
+4. **Concepts** (understanding): only what a developer cannot use the API safely without.
+   Example: idempotency keys, signature verification, settlement timing.
+
+Do not mix them. A how-to links to the reference for every field instead of re-listing it; a
+concept page does not contain steps.
+
+Rules for content:
+
+- Every code sample is complete and runs as written once placeholders are filled. Mark
+  placeholders as `<YOUR_API_KEY>`, `<PAYMENT_ID>`. Samples in several languages do the same
+  thing with the same values.
+- Every field: name, type, required or optional, format, example. Example:
+  `amount` · integer · required · minor units (cents) · `1250`.
+- Every error: code → meaning → what the developer should do. Example:
+  `409 duplicate_request` → the idempotency key was reused with a different body → send a new key
+  or resend the original body.
+- State sandbox versus production differences explicitly, wherever they apply.
+- State security as steps the developer performs: store the key, rotate it, verify each webhook
+  signature before trusting the payload.
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **Overview** (Required): what the integration lets the client do, the main objects, and how
+   the parts fit. One diagram when the flow crosses systems.
+2. **Get started** (Required): prerequisites, getting sandbox credentials, authentication, and
+   one end-to-end example with its expected response.
+3. **How-to guides** (Required): one per client task: goal, steps, expected result, the errors
+   most likely at each step.
+4. **Webhooks** (Required when any exist): events, payloads, delivery and retry behavior,
+   signature verification as numbered steps with code.
+5. **API reference** (Required): endpoints, fields, enums, errors, rate limits and size limits,
+   all in the uniform format above. Link a generated reference when one exists instead of copying.
+6. **Concepts** (Optional): only the ideas a developer needs to use the API correctly.
+7. **Testing and go-live** (Required): sandbox test data and scenarios, the sandbox to production
+   switch, and a go-live checklist the developer can tick.
+8. **Versioning and changelog** (Required): how versions are selected, the deprecation policy,
+   and dated changes once a version has shipped.
+9. **Troubleshooting and support** (Required): common failures with fixes, what to include in a
+   support request, and the public contact channel.
+
+## Done when
+
+- Can a developer with only this guide and sandbox credentials make a first successful call?
+- Does every code sample run as written once placeholders are filled, and match across languages?
+- Does every field state type, required or optional, format and an example?
+- Does every error say what the developer should do?
+- Are sandbox and production differences stated wherever they apply?
+- Are key handling and webhook signature verification given as steps, not advice?
+- Are internal system names, hostnames and non-public behavior absent?
+- Does each how-to end with a result the developer can check?
+
+## Sources
+
+Authored for this skill. Content split informed by the Diátaxis framework (linked, not copied);
+see [sources](../references/sources.md).

package/skills/core/house-style/templates/prd.md

@@ -0,0 +1,81 @@
+# PRD: product requirements
+
+## Use when
+
+The reader is product, design, QA and business stakeholders who do not know the implementation.
+They use the PRD to agree on what users experience and how the product behaves, including
+exceptions, before engineering designs it.
+
+- Pick **brd** instead when the question is why the business needs the change, its objectives and
+  high-level process, not product behavior.
+- Pick **technical-spec** for how engineering builds and verifies it: schemas, APIs, algorithms,
+  migrations, test harnesses.
+A BRD is an input when it exists, not a prerequisite. Do not invent business goals when only a
+feature request was given.
+
+## Tone
+
+Plain product language, low technical depth. A stakeholder must not need to know modules, fields
+or test infrastructure.
+
+## Inputs
+
+- The request, existing behavior, related documents and approved decisions. Material: ask once.
+- Users, entry points, the normal journey, meaningful exceptions and recovery. Material: ask once
+  if the journey cannot be reconstructed.
+- Numbers (limits, thresholds, SLAs). Use the supplied value exactly with its source; never invent
+  one. Material: mark [TBD]. A product choice the PRD exists to make is **Proposed** instead. List
+  both under Product decisions as open.
+- Safety, availability and payment policies are never chosen silently: ask, or record them as open
+  decisions.
+
+## Reasoning
+
+Connect the user problem to the behavior that solves it, then to the boundaries and acceptance
+examples that prove it:
+
+1. Who meets the problem today, and what outcome they need.
+2. The journey: discover, use, return, recover.
+3. The behavior at each step, in user language, with a concrete example of success and of a
+   meaningful failure, interruption or change.
+4. Every default, eligibility rule, precedence and failure policy, stated once under Policies.
+5. The significant choices and why they were made.
+
+Then test for contradictions. Example: an action that is unavailable cannot be the only way to
+recover its own eligibility; a failed check must not look like a negative result.
+
+## Sections
+
+Omit Optional sections that add nothing. Do not pad with empty headings.
+
+1. **Background** (Required): what happens today, who hits the problem, why it matters. Link the
+   BRD if one exists.
+2. **Goal** (Required): the user outcome, scope, and explicit non-goals.
+3. **User journey** (Required): discovery, use, return and recovery where they matter.
+4. **Product requirements** (Required): capabilities and observable behavior, each with a short
+   acceptance example. Example: "Create two agents and customize the model for one. Change the
+   role's default. The uncustomized agent follows the new default on its next task; the customized
+   one keeps its choice."
+5. **Policies** (Required when any exist): defaults, eligibility, precedence, exceptions, failure
+   behavior, visible notifications (trigger, audience, repeats, silent cases). The one place each
+   policy lives. A catalog or a situation → behavior → what the user sees table only when it helps.
+6. **Product decisions** (Required): settled choices and why; open decisions with consequence and
+   owner, clearly marked open. Refer to policies; do not restate them.
+7. **References** (Optional): BRD, designs, the technical spec, sources. Never invent a link to a
+   spec that does not exist yet.
+
+## Done when
+
+- Can a stakeholder with no implementation knowledge follow every requirement?
+- Does every policy appear exactly once, with other sections referring to it?
+- Does each requirement have an observable acceptance example, including at least one failure or
+  recovery case where users can hit one?
+- Are loading, stale, unknown, unavailable and contradictory states explained where users meet them?
+- Is every number either sourced or listed as an open decision with an owner?
+- Is engineering mechanism (schemas, APIs, polling, caching, test fixtures) absent or linked out?
+
+## Sources
+
+Adapted from the retired `prd` skill in this repository (1aboveio/ai, MIT). Structure informed by
+the Atlassian product requirements template (linked, not copied); see
+[sources](../references/sources.md).