@geraldmaron/construct 1.0.18 → 1.0.19

package/skills/roles/operator.release.md

@@ -37,8 +37,16 @@ Additional failure modes on top of the operator core.
 **Why it fails**: regressions show up 30–60 minutes in; if nobody is watching, they compound.
 **Counter-move**: define the post-release watch window (metrics + duration) before pushing. Hold the release until it's clean.
 
+## Methodology
+
+**Progressive delivery.** Ship to a small slice first (canary: 1% → 10% → 50% → 100%, or a ring of low-risk tenants) and let each stage bake for the watch window before widening. The point of a canary is to bound blast radius, so the canary must carry enough real traffic to move the metrics you watch — a canary no one uses proves nothing.
+
+**Make rollback a decision rule, not a judgment call.** Before pushing, write the abort criteria as thresholds on the SLIs that protect the SLO (error rate, latency p99, saturation): "if error rate > X% or p99 > Y ms over Z minutes at any stage, roll back automatically." Wire it so the decision can be automated, and so a tired on-call follows a rule rather than improvising. Roll back, then diagnose — never the reverse.
+
 ## Self-check before shipping
 - [ ] Release is the smallest deployable increment
+- [ ] Staged/canary rollout with a bake window per stage; canary carries real traffic
+- [ ] Abort criteria written as SLI thresholds before push; rollback automatable
 - [ ] Rollback path documented and tested
 - [ ] Core release-facing docs landed with code and match shipped behavior
 - [ ] Post-release watch window defined and staffed

package/skills/roles/operator.sre.md

@@ -37,8 +37,17 @@ Additional failure modes on top of the operator core.
 **Why it fails**: the same incident repeats. Teams lose trust in the process.
 **Counter-move**: every corrective action has an owner, a ticket, and a target date. Review completion in the next monthly.
 
+## Methodology
+
+The error-budget policy is the mechanism that makes an SLO consequential ([Google SRE](https://sre.google/workbook/error-budget-policy/)):
+
+- The budget is `1 − SLO` over a window (99.9% over 28 days ≈ 43 min of allowed downtime). It is spent by every failure, planned or not.
+- **Burn rate** is how fast the budget is being consumed relative to the window. Alert on burn rate with **multi-window** thresholds — a fast-burn alert (e.g. 2% of budget in 1 hour) pages now; a slow-burn alert (e.g. 10% over a few days) opens a ticket. This pages on severity, not on every blip, which is what kills alert fatigue.
+- **The policy is written before the breach**: when the budget is exhausted, feature releases freeze and reliability work takes priority until it recovers; name the exceptions (infra failures, third-party) and who can override. The freeze is the forcing function that balances velocity against reliability — without it the SLO is decorative.
+
 ## Self-check before shipping
 - [ ] Every alert links to a runbook
-- [ ] SLOs have an explicit error-budget policy
+- [ ] SLOs have an explicit, written-before-breach error-budget policy (freeze trigger, exceptions, owner)
+- [ ] Burn-rate alerting uses multi-window thresholds (fast-burn pages, slow-burn ticket)
 - [ ] Dashboards are incident-shaped, not metric-dumps
 - [ ] Post-mortem actions are owned and dated

package/skills/roles/orchestrator.md

@@ -57,10 +57,17 @@ Use this as a fast dispatch checklist before producing orchestration output.
     - Symptom: large reads just to decide who should work.
     - Counter: probe with search, glob, or small reads first.
 
+## Sequencing methodology
+
+- **Graph first**: map each specialist's input→output; parallelize only when no input is another's output. "All parallel"/"all sequential" both mean the graph was skipped.
+- **Waves**: dispatch the set whose inputs are satisfied; the next starts at the slowest member's landing. Minimize waves, not specialists.
+- **Critical path**: total time is the longest dependency chain, not the headcount. On-path specialists delay everything downstream.
+- **Bound fan-out**: cap concurrent dispatch to what the consumer can absorb.
+
 ## Ship Check
 
-- Request classified.
-- Smallest adequate path selected.
+- Request classified; smallest adequate path selected.
+- Dependency graph drawn; specialists grouped into the fewest waves; critical path identified.
 - Handoffs have distinct ownership.
 - Blockers and user questions surfaced.
 - Original ask still matches final output.

package/skills/roles/product-manager.business-strategy.md

@@ -37,8 +37,17 @@ Additional failure modes on top of the product-manager core.
 **Why it fails**: two products with identical features but different economics compete very differently.
 **Counter-move**: for each competitor, model the business (unit economics, distribution, defensibility) not just the surface.
 
+## Methodology
+
+Two frameworks turn "market thesis" from intuition into analysis:
+
+**Structural analysis (Porter's Five Forces).** Assess the industry's profit structure along five forces: rivalry among existing competitors, threat of new entrants, threat of substitutes, bargaining power of buyers, and bargaining power of suppliers. A market where all five are intense is structurally unattractive regardless of how good the product is; the strategy must name which force it is positioned against and what gives durable advantage (cost, differentiation, or focus — not all three).
+
+**Scenario planning.** The future is not a point estimate. Identify the two or three uncertainties that most affect the bet (e.g. "do incumbents add this feature" × "does the buyer consolidate"), cross them into a small set of scenarios, and check the strategy against each. A strategy that only wins in one scenario is a gamble; name the leading signal that tells you which scenario is unfolding, early.
+
 ## Self-check before shipping
 - [ ] Rejected alternatives stated
-- [ ] Market thesis explicit
+- [ ] Market thesis explicit, with the dominant Porter force named
+- [ ] Strategy checked against 2–3 scenarios, not a single forecast
 - [ ] Falsification criterion and revisit threshold declared
 - [ ] Competitive analysis covers economics, not just features

package/skills/roles/researcher.explorer.md

@@ -37,8 +37,19 @@ Additional failure modes on top of the researcher core.
 **Why it fails**: burns the consumer's time and context window; the answer drowns in tangent.
 **Counter-move**: answer the question asked. Link supporting material; don't inline it unless asked.
 
+## Methodology
+
+Explore by following the graph, not by grepping until something looks right:
+
+- **Entry points first**: find where execution starts (CLI dispatch, route table, main, test setup) and trace *forward* along the call graph to the code in question. This locates the real path instead of a same-named decoy.
+- **Both directions**: for a symbol, find its definition and its *callers* (who depends on this) — the blast radius of a change is the caller set, and missing it is how "small" changes break distant things.
+- **Triangulate before concluding**: confirm a behavior from at least two of {the code, a test that exercises it, a config that wires it}. A single grep hit is a lead, not a conclusion.
+- **Name the seams**: report where control crosses module/process/service boundaries; that is where the question usually actually lives.
+
 ## Self-check before shipping
+- [ ] Traced from an entry point along the call graph, not from an isolated grep hit
+- [ ] Both definition and callers (dependency blast radius) identified
+- [ ] Behavior triangulated across code + test/config, not a single match
 - [ ] Every claim cites a path, ideally with a line
 - [ ] Function behavior verified from the body, not the name
-- [ ] Searched multiple naming variants and entry points
 - [ ] Response scoped to the question asked

package/skills/roles/researcher.ux.md

@@ -37,8 +37,20 @@ Additional failure modes on top of the researcher core.
 **Why it fails**: collapses the problem-space exploration into a solution bias; design has less room to iterate.
 **Counter-move**: report the problem (friction, confusion, unmet need). Let design own the solution.
 
+## Methodology
+
+The failure modes above are what to avoid. This is the rigor a senior UX researcher brings.
+
+**Validity — name the threat.** Every study has four validity questions: *internal* (did the thing you changed cause the effect, or a confound?), *external* (does it generalize beyond these participants/tasks?), *construct* (does the measure capture the concept, or a proxy?), and *conclusion* (is the difference real or noise?). State which is weakest for this study; that is where the finding is most likely wrong.
+
+**Sampling.** Sample size follows the claim, not the calendar. For discovering usability problems, ~5 participants per distinct user segment surfaces most issues — but that is *per segment*, and it finds problems, it does not measure their rate. Rate and preference claims need a powered sample; state the segment, N, and how participants were recruited (recruitment bias is the usual confound).
+
+**Inter-rater reliability.** When themes are coded from qualitative data, two coders should code a sample independently and agree before the coding is trusted. Persistent disagreement means the codebook, not the data, is unfinished — fix the codebook.
+
 ## Self-check before shipping
 - [ ] Questions focus on past behavior, not hypothetical future
 - [ ] Observed behavior weighted over self-report
-- [ ] Sample size stated for every claim
+- [ ] Weakest validity threat (internal/external/construct/conclusion) named
+- [ ] Sample size and segment stated for every claim; recruitment noted
+- [ ] Themes coded with inter-rater agreement, not a single coder
 - [ ] Findings describe problems, not prescribe solutions

package/skills/roles/reviewer.devil-advocate.md

@@ -37,8 +37,20 @@ Additional failure modes on top of the reviewer core.
 **Why it fails**: slows down learning that should be fast; teams stop bringing you early ideas.
 **Counter-move**: classify the decision on the reversibility axis first. Calibrate pushback accordingly.
 
+## Methodology
+
+Beyond ad-hoc objection, run the plan through a structured failure-mode pass (FMEA — failure mode and effects analysis):
+
+- For each component or step, ask *how could this fail* (the failure mode), *what happens when it does* (effect), and *why might it happen* (cause).
+- Score each on three axes 1–10: **severity** (how bad the effect), **occurrence** (how likely the cause), **detection** (how likely you'd catch it before harm — high score = hard to detect). Their product is the **risk priority number (RPN)**.
+- Rank by RPN, not by which objection came to mind first. A low-severity but undetectable-and-frequent failure can outrank a dramatic but obvious one.
+- The highest-RPN modes are where the plan needs a mitigation or a detection point before it ships; explicitly mark the rest "acknowledge but proceed."
+
+This turns "this seems risky" into a ranked, defensible list the author can act on.
+
 ## Self-check before shipping
-- [ ] Each objection names a concrete scenario
+- [ ] Each objection names a concrete scenario (failure mode + effect + cause)
 - [ ] At least three categories of risk covered
-- [ ] Objections ranked by severity
+- [ ] Objections ranked by RPN (severity × occurrence × detection), not recency
+- [ ] Highest-RPN modes have a mitigation or detection point
 - [ ] Reversibility of the decision assessed

package/skills/roles/reviewer.evaluator.md

@@ -37,8 +37,21 @@ Additional failure modes on top of the reviewer core.
 **Why it fails**: can't tell which change did what; can't roll back specifically if quality regresses.
 **Counter-move**: change one variable at a time. Pin the others.
 
+## Methodology
+
+The failure modes above are what to avoid. This is the discipline that separates a senior evaluator from a mid-level one.
+
+**Rubric design.** A usable rubric has criteria that are *independent* (scoring one does not force another), *observable* (two reviewers reading the same output land within one level), and *level-anchored* (each level has a concrete descriptor, not just a number). Write one positive and one negative exemplar per criterion before scoring anything. If you cannot write the negative exemplar, the criterion is not yet measurable.
+
+**Ground truth.** A score is only as good as the labels it is measured against. State how ground truth was established (expert label, consensus, reference output), and measure inter-rater reliability when more than one labeler is involved — disagreement above a small threshold means the rubric, not the output, is the problem. Resolve disagreements by tightening the rubric, not by averaging.
+
+**False positives vs false negatives.** Name which error is more costly for this evaluation *before* setting the threshold. An eval that gates releases should tolerate false negatives and false positives asymmetrically depending on what the gate protects — shipping a regression is usually worse than blocking a good change. State the asymmetry; a single accuracy number hides it.
+
+**Statistical significance.** Sample size follows from the smallest difference worth detecting, not from convenience. Report N, and for pass-rate claims report the interval, not just the point estimate — a 2-point improvement on N=20 is noise. When comparing to baseline, a difference inside the intervals is not a result; say so rather than reporting the delta as if it were real.
+
 ## Self-check before shipping
-- [ ] Rubric declared before scoring
-- [ ] Sample size reported and defensible
-- [ ] Baseline comparison included
-- [ ] One variable changed per run; others pinned
+- [ ] Rubric declared before scoring, with a positive and negative exemplar per criterion
+- [ ] Ground-truth basis stated; inter-rater reliability checked when multiple labelers
+- [ ] False-positive vs false-negative cost asymmetry named before the threshold was set
+- [ ] Sample size justified by the smallest meaningful difference; interval reported, not just point estimate
+- [ ] Baseline comparison included; one variable changed per run, others pinned

package/skills/roles/reviewer.trace.md

@@ -37,8 +37,19 @@ Additional failure modes on top of the reviewer core.
 **Why it fails**: the final output may mask a degraded path that costs time, money, or reliability.
 **Counter-move**: examine the full tool-call chain. Flag any failure, retry, or fallback.
 
+## Methodology
+
+Treat fleet scores as a process to monitor, not a number to eyeball (statistical process control):
+
+- Establish a **baseline** distribution — mean and standard deviation of the score over a stable window — before calling anything a regression.
+- A run is out of control when it crosses a **control limit** (commonly ~3σ from the mean) or shows a non-random pattern (e.g. several consecutive points drifting one direction). A single point inside the limits is noise, not signal — do not chase it.
+- Separate **common-cause** variation (inherent noise; do not react per-point) from **special-cause** variation (a real shift; investigate). Reacting to common-cause noise — "tampering" — makes variance worse.
+- Watch the **variance**, not just the median: a stable median can hide a widening spread where a subset of agents is failing. Report the spread alongside the central tendency.
+
 ## Self-check before shipping
-- [ ] Judged against a sampled distribution, not one trace
+- [ ] Judged against a sampled distribution with a baseline mean and spread
+- [ ] Out-of-control points distinguished from common-cause noise (no tampering)
+- [ ] Variance reported, not just the median
 - [ ] Each issue cites a specific span or tool call
 - [ ] Latency and quality reported separately
 - [ ] Full tool-call chain examined

package/skills/roles/security.legal-compliance.md

@@ -42,7 +42,15 @@ Additional failure modes on top of the security core.
 **Why it fails**: contaminates the license of the whole product; costly to unwind later.
 **Counter-move**: automated license scan in CI; allowlist policy per product tier.
 
+## Methodology
+
+**Map obligations to controls through a risk register, not a checklist.** For each regulation in scope (GDPR, CCPA, HIPAA, EU AI Act, …), enumerate the obligations, and for each record: the control that satisfies it, where that control lives in code or process, its owner, and the residual risk if it fails. An obligation with no mapped control is an open finding; a control with no test is compliance theater. This register is the bridge between legal text and the system — it is what lets you answer an auditor (or an incident) with evidence rather than prose.
+
+**Frame risk in business terms.** Rate each gap by likelihood × impact, where impact spans regulatory penalty, contractual liability, and trust. This lets non-lawyers prioritize: a low-likelihood/high-penalty gap (a deletion path that exists but is untested) and a high-likelihood/low-penalty one demand different responses. Translate "the regulation says X" into "if we don't do X, the exposure is Y" so the trade-off is decidable by the people who own the budget.
+
 ## Self-check before shipping
+- [ ] Each in-scope obligation maps to a control, owner, and residual-risk note in a register
+- [ ] Gaps rated by likelihood × impact (penalty, liability, trust)
 - [ ] Policies map to testable controls
 - [ ] Retention enforced by automated deletion
 - [ ] Consent granular, opt-in, withdrawable

package/skills/roles/security.md

@@ -58,8 +58,19 @@ Load this before drafting. These are the failure modes that separate strong role
 **Why it fails**: gives an attacker a map of the system; turns a reconnaissance step into a freebie.
 **Counter-move**: user-facing errors are generic. Detailed context goes to logs with appropriate access controls.
 
+## Methodology
+
+Threat modeling is a process, not an instinct. Run it explicitly:
+
+- **Decompose**: draw the data-flow — trust boundaries, entry points, assets, and where data crosses from less-trusted to more-trusted.
+- **Enumerate with STRIDE** per element: **S**poofing, **T**ampering, **R**epudiation, **I**nformation disclosure, **D**enial of service, **E**levation of privilege. STRIDE forces coverage of categories an ad-hoc review skips (repudiation and tampering are the usual blind spots).
+- **Rate and rank**: score each threat by likelihood × impact (or DREAD/CVSS where a number is needed), and treat the highest first. For higher-stakes systems, escalate to an attacker-simulation pass (PASTA) that reasons from an adversary's goals and capabilities, not just a category list.
+- **Decide per threat**: mitigate, accept (with rationale), or transfer. An unrated threat is an unmade decision.
+
 ## Self-check before shipping
 
+- [ ] Threat model decomposes data flow and enumerates STRIDE per trust boundary
+- [ ] Threats rated and ranked; highest-risk handled first
 - [ ] No single control is the only line of defense
 - [ ] Secrets live in a secret manager, not in the repo
 - [ ] User input is validated and escaped at every boundary

package/specialists/contracts.json

@@ -133,6 +133,18 @@
           "check": "artifact-has-section",
           "section": "Rejected Alternatives"
         },
+        {
+          "id": "adr-reversibility-stated",
+          "description": "ADR Reversibility section is present and non-empty",
+          "check": "artifact-section-nonempty",
+          "section": "Reversibility"
+        },
+        {
+          "id": "adr-consequences-stated",
+          "description": "ADR Consequences section is present and non-empty",
+          "check": "artifact-section-nonempty",
+          "section": "Consequences"
+        },
         {
           "id": "adr-numeric-claims-cited",
           "description": "Every numeric claim in the ADR body cites a source",
@@ -547,6 +559,12 @@
           "check": "artifact-has-section",
           "section": "Market Context"
         },
+        {
+          "id": "strategic-memo-options-nonempty",
+          "description": "Strategic memo Options section is present and non-empty",
+          "check": "artifact-section-nonempty",
+          "section": "Options"
+        },
         {
           "id": "strategic-memo-has-strategic-risks",
           "description": "Strategic memo must contain a Strategic Risks section",

package/specialists/prompts/cx-researcher.md

@@ -46,7 +46,9 @@ When querying search engines or paper indexes, always filter or sort by date: ne
 
 1. **Primary**: peer-reviewed papers, official docs for the exact version, published standards, raw source code, SEC filings, primary company announcements
 2. **Secondary**: changelogs, migration guides, tracked GitHub issues, maintainer posts, conference talks by the authors
-3. **Tertiary**: blog posts, forums, Q&A, analyst summaries, AI-generated overviews: used only to locate primaries, never as evidence
+3. **Tertiary**: blog posts, forums, Q&A, analyst summaries, AI-generated overviews: used only to locate primaries, never as evidence for factual claims
+
+Class is relative to the claim (`rules/common/research.md` §2): community/forum content (Reddit, Stack Overflow, HN) is **primary** evidence for sentiment, demand, and friction claims — admissible under the §10 checklist (corroborated, recent, engagement-backed) — and tertiary for factual claims. For community signal by domain, start from `rules/common/research-sources.md`. Grade every source on the Admiralty scale (reliability `A`–`F` × credibility `1`–`6`, e.g. `B2`) and map confidence accordingly: `high` only on `A1`/`A2`/`B1`.
 
 ### Step 4: Check internal evidence
 
@@ -76,7 +78,7 @@ Produce a research brief using the structure from `get_template("research-brief"
 
 **METHOD**: search terms, systems queried, date filters applied, domain starting points used, internal paths checked; enough detail to reproduce
 
-**SOURCES**: structured table: title/path | class (primary/secondary/tertiary) | date | URL | verified (yes/no) | relevance
+**SOURCES**: structured table: title/path | class (primary/secondary/tertiary) | reliability (A–F) | credibility (1–6) | date | URL | verified (yes/no) | relevance
 
 **FINDINGS**: each finding labeled: what the source says (observation) | what is inferred (inference) | confidence (high/medium/low) | supporting source(s)
 

package/templates/docs/backlog-proposal.md

@@ -11,7 +11,7 @@ autonomously; applying it requires explicit approval.
 -->
 
 ## Source evidence
-<!-- Evidence brief, PRD, customer notes, tickets, or research supporting the proposal. -->
+<!-- Evidence brief, PRD, customer notes, tickets, or research supporting the proposal, each with its evidence grade (rules/common/research.md §10). A proposal resting only on low-graded or uncorroborated evidence should be a signal brief, not a backlog item. -->
 
 ## Proposed changes
 <!-- Table: create/update, target issue if any, title, rationale, evidence, acceptance criteria. -->

package/templates/docs/customer-profile.md

@@ -16,7 +16,7 @@ asks for cleanup. Keep facts tied to source evidence.
 <!-- Stack, tools, integrations, scale, constraints, and relevant operating model. -->
 
 ## Active pain points
-<!-- Current friction, with source links or dates. Distinguish severe blockers from preferences. -->
+<!-- Current friction, each with a source link, a date, and its evidence grade (rules/common/research.md §10). Distinguish severe blockers from preferences, and a one-off mention from a corroborated pattern. -->
 
 ## Open asks
 <!-- Table: ask, first raised, times mentioned, source, linked issue, status. -->

package/templates/docs/evidence-brief.md

@@ -19,7 +19,11 @@ source lists or grouped findings. Keep em dashes rare.
 <!-- State the minimum signal needed to proceed. Example: two independent customers, three repeated mentions, or one severe enterprise blocker. -->
 
 ## Sources
-<!-- Table: source, source class, date/access date, customer or actor, link/path, confidence, and whether it is direct evidence or secondhand summary. -->
+<!-- Class is relative to the claim (rules/common/research.md §2); Reliability (A–F) and Credibility (1–6) are the Admiralty grade (§10). Direct = first-hand evidence vs secondhand summary. -->
+
+| Source | Class | Reliability | Credibility | Date | Actor | Link / Path | Direct? |
+|---|---|---|---|---|---|---|---|
+| {title} | primary / secondary / tertiary | A–F | 1–6 | {YYYY-MM-DD} | {customer or actor} | {url or path} | direct / secondhand |
 
 ## What we observed
 <!-- Factual observations only. Separate direct evidence from interpretation. -->

package/templates/docs/incident-report.md

@@ -3,44 +3,60 @@
 - **Incident ID**: {INC-NNNN}
 - **Date**: {YYYY-MM-DD}
 - **Severity**: SEV-1 | SEV-2 | SEV-3
-- **Duration**: {start} → {end} ({total})
-- **Authors**: {names}
+- **Duration**: {detection} → {all-clear} ({total}; time-to-detect {ttd}, time-to-mitigate {ttm})
+- **Authors**: {names — include everyone who responded}
 - **Status**: draft | final
 
+<!--
+Blameless postmortem. Describe systems and decisions, not people. Neutral, factual
+language — no dramatic or animated descriptions. Publish within days while detail is
+fresh, and share widely. See Google SRE postmortem culture:
+https://sre.google/workbook/postmortem-culture/
+-->
+
 ## Summary
-<!-- Two to four sentences. What happened, who was affected, how it was resolved. Blameless tone. -->
+<!-- Two to four sentences: what happened, who was affected, how it was resolved. Blameless tone. -->
+
+## Severity rationale
+<!-- Why this severity and not one higher or lower? State the criteria (user impact, data integrity, duration, blast radius). If it was reclassified mid-incident, say when and why. -->
 
 ## Impact
-<!-- Users affected, requests failed, revenue lost, data integrity consequences. Quantify. -->
+<!-- Quantify: users affected, requests failed, error rate, revenue, data-integrity consequences. "Unknown" is acceptable; a guess is not. -->
 
 ## Timeline
-<!-- Times in UTC. Key events: detection, diagnosis, mitigation, resolution, all-clear. One line per event. -->
+<!-- Times in UTC, one line per event. Mark the key transitions explicitly: detection, diagnosis, mitigation start, resolution, all-clear. The gaps between them are the response story. -->
 
-| Time (UTC) | Event |
-|------------|-------|
-| {HH:MM}    | {what happened or what was done} |
+| Time (UTC) | Event | Phase |
+|------------|-------|-------|
+| {HH:MM}    | {what happened or was done} | detection / diagnosis / mitigation / resolution |
+
+## Trigger
+<!-- The proximate cause — the specific change, event, or input that set the incident off (a deploy, a traffic spike, a dependency failure). Distinct from the root cause. -->
 
 ## Root cause
-<!-- The underlying cause, not just the proximate trigger. The five-whys, condensed. -->
+<!-- The underlying system condition that let the trigger cause harm. The five-whys, condensed. A root cause is a system/design gap, never a person. -->
 
 ## Contributing factors
-<!-- Conditions that made the incident possible, worse, or harder to resolve. Include process gaps, not just code. -->
+<!-- Conditions that made the incident possible, worse, or harder to resolve: missing alerts, brittle dependencies, process gaps, absent runbook. Not the root cause, but they shaped the outcome. -->
 
-## What went well
-<!-- Detection, response, communication, tooling. Keep this honest. -->
+## Mitigators
+<!-- What went right and reduced blast radius — a circuit breaker that tripped, a canary that caught it, a fast rollback. These are as instructive as the failures; preserve them. -->
 
-## What went poorly
-<!-- Be specific. Blameless, not blameless-to-the-point-of-vague. -->
+## Detection and response
+<!-- How was it detected (alert, customer report, dashboard)? Was detection fast enough? What slowed diagnosis or mitigation? Be specific and blameless. -->
 
-## Corrective actions
-<!-- Each action: owner, deadline, ticket link. Prefer systemic fixes over "be more careful". -->
+## Action items
+<!-- Each action: systemic fix preferred over "be more careful". Owner, priority, and tracking ID required. Priority: P0 (prevents recurrence, do now) → P2 (hardening). -->
 
-| Action | Owner | Deadline | Ticket |
-|--------|-------|----------|--------|
-| {what} | {who} | {date}   | {link} |
+| Action | Type (prevent/detect/mitigate) | Owner | Priority | Tracking |
+|--------|--------------------------------|-------|----------|----------|
+| {what} | {prevent/detect/mitigate}      | {who} | P0/P1/P2 | {bd or ticket} |
 
 ## Lessons learned
-<!-- What this incident revealed about the system or the organization. -->
+<!-- Organized by theme. What did this reveal about the system or the organization that generalizes beyond this incident? -->
+
+## Glossary
+<!-- Define domain-specific terms, service names, and acronyms used above so a reader outside the team can follow the report. -->
 
 ## References
-<!-- Logs, dashboards, traces, related incidents, PRs that caused or fixed the issue. -->
+<!-- Logs, dashboards, traces (with IDs preserved), related incidents, the PRs that caused and that fixed the issue. -->

package/templates/docs/prfaq.md

@@ -16,13 +16,13 @@ or directly from evidence, but it must not invent customer demand.
 <!-- Two or three paragraphs grounded in evidence. Explain the customer problem, why now, and what is missing today. -->
 
 ## Press release
-<!-- Write as if the capability has shipped. Focus on customer outcome, not implementation. -->
+<!-- Write as if the capability has shipped. Focus on customer outcome, not implementation. Include a spokesperson quote and a customer quote — mark a hypothetical quote as such; never invent an attributed one (rules/common/no-fabrication.md). -->
 
 ## External FAQ
 <!-- Customer-facing questions and answers. Keep answers concrete and honest about limits. -->
 
 ## Internal FAQ
-<!-- Questions from engineering, sales, support, security, finance, and leadership. Include unknowns as TBD with what would resolve them. -->
+<!-- Questions from engineering, sales, support, security, finance, and leadership. Include unknowns as TBD with what would resolve them. Cover the launch/success metrics: what target defines success and by when. -->
 
 ## Evidence appendix
 <!-- Source links, customer quotes, related issues, research, and PRDs. -->

package/templates/docs/product-intelligence-report.md

@@ -13,7 +13,7 @@ without becoming a backlog dump.
 <!-- Two or three paragraphs. What changed, what matters, and what decision should follow. -->
 
 ## Evidence base
-<!-- Summary of source types, coverage, recency, and known gaps. -->
+<!-- Source types, coverage, recency, and known gaps. Grade the evidence (rules/common/research.md §10); for community/sentiment sources note corroboration. Each theme below inherits the strength of the evidence under it — do not report a strong theme on weakly-graded sources. -->
 
 ## Themes
 <!-- Each theme should include evidence strength, affected personas, representative sources, and counter-signal. -->

package/templates/docs/research-brief.md

@@ -23,14 +23,16 @@
 
 ## Sources
 
-| Title / Path | Class | Date | URL | Verified | Relevance |
-|---|---|---|---|---|---|
-| {source title or file path} | primary / secondary / tertiary | {YYYY-MM-DD} | {URL or path} | yes / no / n/a | {one-line} |
+| Title / Path | Class | Reliability | Credibility | Date | URL | Verified | Relevance |
+|---|---|---|---|---|---|---|---|
+| {source title or file path} | primary / secondary / tertiary | A–F | 1–6 | {YYYY-MM-DD} | {URL or path} | yes / no / n/a | {one-line} |
 
-<!-- Class definitions:
-  - primary: peer-reviewed papers, official docs at exact version, raw source code, standards, company announcements, SEC filings
+<!-- Class is relative to the claim (rules/common/research.md §2): community/forum content is
+  primary for sentiment/experience claims, tertiary for factual ones.
+  - primary: peer-reviewed papers, official docs at exact version, raw source code, standards, company announcements, SEC filings; first-hand accounts for the attitude they express
   - secondary: changelogs, migration guides, tracked issues, maintainer posts, conference talks by authors
-  - tertiary: blog posts, forums, Q&A, analyst summaries: for discovery only, never as evidence
+  - tertiary: blog posts, forums, Q&A, analyst summaries: for factual claims, discovery only
+  Reliability (A–F) and Credibility (1–6) are the Admiralty grade (research.md §10); record both, e.g. B2.
   Mark Verified = yes only after fetching the URL and confirming content matches. -->
 
 ## Findings

package/templates/docs/research-finding.md

@@ -1,26 +1,51 @@
 ---
 kind: research-finding
 topic: "<short topic line>"
-confidence: inferred
+confidence: high | medium | low
 sources: []
 created: <ISO timestamp set by construct knowledge add>
-expiresAt: <ISO timestamp, default created + 90d>
+expiresAt: <ISO timestamp, default created + 90d; shorten for fast-moving topics>
 profile: <active profile id>
 ---
 
+<!--
+A lightweight but rigorous knowledge-store entry. Same evidence standard as a
+research brief, condensed: observation separated from inference, every finding
+cited, confidence tied to source grade, an explicit refresh trigger. See
+rules/common/research.md.
+-->
+
+## SOURCES
+
+| Title / Path | Class | Reliability | Credibility | Date | URL | Verified |
+|---|---|---|---|---|---|---|
+| {source} | primary / secondary / tertiary | A–F | 1–6 | {YYYY-MM-DD} | {url} | yes / no |
+
 ## FINDINGS
 
-- <Finding 1 with citation>
-- <Finding 2 with citation>
+<!-- Observation only: what the source states. Each finding cites a source row above. -->
+
+- <Finding 1 [source: …]>
+- <Finding 2 [source: …]>
 
 ## INFERENCES
 
-- <Inference labeled as such>
+<!-- What is concluded beyond what any single source says. Labeled as inference, not fact. -->
+
+- <Inference, with the findings it rests on>
+
+## CONFIDENCE
+
+<!-- high / medium / low, with the reasoning: tie it to the Admiralty grade of the sources (research.md §10). high only on A1/A2/B1. Name the strongest counter-evidence. -->
 
 ## GAPS
 
-- <What we could not confirm>
+- <What could not be confirmed and would change the conclusion if known>
 
 ## RECOMMENDATION
 
-- <Next action based on the evidence available>
+- <Next action based on the evidence available, and the threshold that would change it>
+
+## REFRESH
+
+<!-- When this finding should be re-verified: the expiresAt date, or the event that would invalidate it (a new release, a superseding paper). -->

package/templates/docs/rfc.md

@@ -22,7 +22,19 @@ contract, API, schema, or protocol consumed by other systems.
 <!-- What problem or limitation drives this proposal? Include evidence: incidents, performance data, support tickets, developer friction. Explain why the status quo is not acceptable. -->
 
 ## Proposed design
-<!-- The concrete proposal. Enough detail for reviewers to evaluate feasibility and tradeoffs. Diagrams, code sketches, and data models are appropriate here. -->
+<!-- The concrete proposal. Enough detail for reviewers to evaluate feasibility and tradeoffs. The sequence below shows the proposed behavior in context — include the happy path and at least one error path. -->
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Service
+  participant Store
+  Client->>Service: request
+  Service->>Store: read or write
+  Store-->>Service: result
+  Service-->>Client: response
+  Note over Service,Store: error path — Store unavailable → Service returns degraded response
+```
 
 ## Tradeoffs and alternatives
 <!-- The other credible designs considered. For each: what it is, why it was not chosen, and under what conditions it would be preferred. No strawmen. -->

package/templates/docs/runbook.md

@@ -14,8 +14,27 @@
 ## Impact
 <!-- Who is affected and how badly. Data loss? Degraded performance? Complete outage? -->
 
+## Severity and response
+<!-- Map each severity to the response it triggers: page urgency, comms cadence, and error-budget consequence. A SEV-1 pages immediately and freezes related releases per the error-budget policy (https://sre.google/workbook/error-budget-policy/); a SEV-3 is handled in business hours. -->
+
+| Severity | Trigger condition | Page within | Comms | Error budget |
+|----------|-------------------|-------------|-------|--------------|
+| SEV-1 | {full outage / data loss / SLO breach} | 5 min | exec + status page | breach → freeze releases |
+| SEV-2 | {major degradation, workaround exists} | 15 min | team + stakeholders | partial spend |
+| SEV-3 | {minor / single-tenant / cosmetic} | business hours | team channel | none |
+
 ## Diagnostic steps
-<!-- Ordered checks from cheapest to most expensive. Each step: what to check, how to check it, what the answer means. -->
+<!-- Ordered checks from cheapest to most expensive. Each step: what to check, how to check it, what the answer means. Keep the decision tree below in sync with the steps. -->
+
+```mermaid
+flowchart TD
+  A[Alert fires] --> B{Error rate elevated?}
+  B -->|Yes| C[Check upstream dependency health]
+  B -->|No| D{User-visible impact?}
+  C --> E[Apply remediation]
+  D -->|Yes| C
+  D -->|No| F[Monitor and stand down]
+```
 
 ## Remediation
 <!-- The fix. Step-by-step, with exact commands or UI paths. Include expected output for each step. -->

package/templates/docs/signal-brief.md

@@ -13,7 +13,10 @@ without pretending the requirements are ready.
 <!-- One or two paragraphs. What appears to be happening, and where the signal came from. -->
 
 ## Evidence
-<!-- Cite the concrete notes, tickets, customer quotes, traces, or analytics that support the signal. -->
+<!-- Cite the concrete notes, tickets, customer quotes, traces, or analytics. Grade each source with its Admiralty reliability/credibility (rules/common/research.md §10); for community sources note corroboration and engagement. The signal strength above should follow from the grades, not precede them. -->
+
+## Counter-signal
+<!-- The strongest evidence against the signal, or its absence. A signal no one tried to disconfirm is weaker than it looks. -->
 
 ## Why it matters
 <!-- What product, customer, or business decision this could affect if the signal strengthens. -->