@geraldmaron/construct 1.0.18 → 1.0.20

package/rules/common/research-sources.md

@@ -0,0 +1,32 @@
+---
+description: Per-domain community starting points for sentiment and signal research.
+enforced_by: rules/common/research.md
+adr_reference: ADR-0017
+---
+# Community source catalog
+
+Starting points for **community signal** — sentiment, demand, friction, adoption experience — organized by research domain. These complement, never replace, the authoritative starting points in [research.md §2](research.md). Community sources are admissible only under the §10 checklist, and only for sentiment/experience claims (a source's class is relative to the claim — see research.md §2).
+
+Treat every entry as a starting point, not a settled citation: confirm the venue is still active and record the post date and Admiralty grade (research.md §4, §10) before any community source becomes load-bearing.
+
+| Domain | Reddit | Other community venues |
+|---|---|---|
+| AI tools, LLMs, agents | r/LocalLLaMA, r/MachineLearning, r/LanguageTechnology | Hacker News (Show HN / Ask HN), arXiv-sanity discussions, vendor Discords |
+| Developer tools, IDEs, languages | r/programming, r/webdev, r/javascript, r/Python, r/rust, r/golang | Stack Overflow (by tag) + the annual Developer Survey, Hacker News, Lobsters |
+| DevOps, platform, reliability | r/devops, r/sre, r/kubernetes, r/Terraform | CNCF Slack, Hacker News, platform vendor Discords |
+| Security, vulnerabilities | r/netsec, r/cybersecurity, r/AskNetsec | HackerOne / Bugcrowd public disclosures, OSS-Security mailing list, Hacker News |
+| Cloud infra, APIs, SDKs | r/aws, r/AZURE, r/googlecloud | Vendor community forums, provider Discords, Stack Overflow tags |
+| Data / ML engineering | r/dataengineering, r/MachineLearning, r/datascience | dbt Community Slack, Hacker News |
+| Product, market, adoption | r/SaaS, r/ProductManagement, r/startups | Hacker News (launches), Product Hunt discussion |
+| Regulatory, compliance, privacy | r/privacy, r/gdpr | IAPP community forums (primary regulation text remains the authority) |
+
+## How to read community signal
+
+- **Corroboration over volume from one place.** The same pain point raised independently across multiple threads or subreddits is stronger than one viral post.
+- **Engagement is evidence of resonance, not of truth.** High upvotes mean many people relate to the sentiment; they do not make a factual claim in the post true.
+- **Recency matters most for fast-moving domains** (research.md §1) — a frustration from two years ago may already be resolved.
+- **Record the grade.** Community sentiment sources are typically `D`–`F` on reliability; they reach `1`–`2` on credibility only when cross-corroborated. Do not inflate.
+
+## References
+
+- [Reddit](https://www.reddit.com), [Hacker News](https://news.ycombinator.com), [Stack Overflow Developer Survey](https://survey.stackoverflow.co)

package/rules/common/research.md

@@ -29,6 +29,17 @@ Use the narrowest, most authoritative starting point for the research domain:
 
 Tertiary sources (blogs, forums, Q&A, AI-generated summaries) may help locate primaries. They are not sufficient evidence for load-bearing claims.
 
+For where to look for community signal by domain, see [research-sources.md](research-sources.md).
+
+### Source class is relative to the claim
+
+A source's class is not fixed — it depends on what the claim is about. The same artifact can be primary for one claim and tertiary for another.
+
+- A Reddit thread is **tertiary** for "what does API X do" (the spec is primary), but **primary** for "developers report friction with API X's DX" — a first-hand account is primary evidence of the attitude it expresses.
+- A vendor blog post is **secondary** for a feature's behavior (the docs/source are primary), but **primary** for "the vendor publicly committed to X on date Y."
+
+Classify by the claim. For sentiment, demand, adoption-experience, and friction claims, community and forum content is admissible primary evidence under the conditions in §10. For factual, version, security, pricing, and compatibility claims, community content stays tertiary — locate the primary.
+
 ## 3. Start order
 
 Start with the narrowest authoritative source that can answer the question:
@@ -52,7 +63,8 @@ Start with the narrowest authoritative source that can answer the question:
 Record:
 
 - source title or path
-- source class: internal, primary, secondary, or tertiary
+- source class: internal, primary, secondary, or tertiary (for the specific claim — see §2)
+- Admiralty grade: source reliability `A`–`F` and information credibility `1`–`6` (see §10), recorded together, e.g. `B2`
 - version or revision when applicable
 - publication date, release date, or access date
 - why this source is relevant
@@ -119,7 +131,52 @@ Research outputs should include:
 
 Every substantive finding should point to a verified source path, URL, or document reference.
 
-## 10. Anti-patterns
+## 10. Community sources, credibility grading, and signal
+
+Community sources (Reddit, Stack Overflow, Hacker News, Discord, GitHub Discussions) are admissible as **primary evidence of sentiment, demand, friction, and adoption experience** (§2) — never as evidence for factual, version, security, pricing, or compatibility claims, where the primary must be located.
+
+### Admissibility checklist
+
+A community source supports a load-bearing sentiment/demand claim only when:
+
+- the venue is identified (which subreddit/tag/thread) and the post date is recorded;
+- the signal is corroborated — multiple independent threads/posts, or one high-engagement thread (substantial upvotes and a comment consensus), not a single low-engagement post;
+- it is recent enough for the topic's pace (§1);
+- the claim is about expressed experience or opinion, not a fact the poster is merely repeating.
+
+A single anonymous low-engagement post is noise. Cross-thread agreement, repeated independently-raised pain points, and high-engagement consensus are signal. State which you have.
+
+### Admiralty grade
+
+Grade every source on two independent axes, adapted from the NATO Admiralty Code, and record them together (e.g. `A1`, `B2`, `D4`). The axes are independent: a usually-reliable source can carry improbable information (`B5`), and an unreliable source can report something independently confirmed (`E1`).
+
+Source reliability:
+
+| Grade | Meaning |
+|---|---|
+| A | Completely reliable — authoritative primary, history of reliability (official docs, standards, peer-reviewed) |
+| B | Usually reliable — minor doubt (reputable vendor docs, established maintainers) |
+| C | Fairly reliable — some doubt, valid in the past (reputable secondary reporting) |
+| D | Not usually reliable — significant doubt (unvetted blogs, single-author claims) |
+| E | Unreliable — history of invalid information |
+| F | Cannot be judged — no basis to evaluate (anonymous, no track record) |
+
+Information credibility:
+
+| Grade | Meaning |
+|---|---|
+| 1 | Confirmed by other independent sources; consistent with known information |
+| 2 | Probably true — not confirmed, but logical and consistent |
+| 3 | Possibly true — not confirmed, reasonably logical, partial agreement |
+| 4 | Doubtful — not confirmed, possible but not logical, uncorroborated |
+| 5 | Improbable — contradicted by other information |
+| 6 | Cannot be judged — insufficient basis |
+
+Confidence mapping: a load-bearing claim may be stated `high` only on `A1`/`A2`/`B1`; `medium` on `B2`/`C2`/`C3`; otherwise `low`. Community sentiment sources are typically `D`–`F` on reliability but can reach `1`–`2` on credibility when cross-corroborated — record both honestly rather than inflating the claim.
+
+References: [NATO Admiralty Code](https://en.wikipedia.org/wiki/Admiralty_code), [primary-source definition](https://en.wikipedia.org/wiki/Primary_source).
+
+## 11. Anti-patterns
 
 Do not:
 

package/skills/roles/data-engineer.pipeline.md

@@ -31,8 +31,20 @@ Additional failure modes on top of the data engineer core.
 **Why it fails**: data breaks at the consumer boundary.
 **Counter-move**: publish contracts and run compatibility checks before deploy.
 
+## Methodology
+
+The monitors above tell you a job broke; lineage and SLAs tell you what it broke and whether that matters.
+
+**Lineage.** Every dataset should trace column-to-column from source to consumer, so that when a value is wrong you can answer "what fed this" and "what depends on this" without log archaeology. Capture lineage as metadata (which job, which inputs, which transform), not tribal knowledge; it is what makes an incident's blast radius computable.
+
+**Data SLAs / SLOs.** A pipeline without a stated freshness and completeness target has no definition of "broken." Set an SLA per consumed dataset (e.g. "fresh within 1h, 99.5% of rows present") and alert against the SLO, not against raw job status — a job that "succeeded" but delivered half the rows is a breach. Tie the SLA to the consumer's actual decision cadence, not to convenience.
+
+**Observability maturity.** Progress from "is the job green" → "is the data fresh and complete" → "is the distribution sane" (volume/null-rate/value drift). The last catches the silent corruption the first two miss.
+
 ## Self-check before shipping
 - [ ] Reruns, retries, and backfills are idempotent
-- [ ] Freshness, volume, schema, latency, and error monitors exist
+- [ ] Column-level lineage from source to consumer is captured as metadata
+- [ ] A freshness/completeness SLA exists per consumed dataset; alerts fire on SLO breach, not just job failure
+- [ ] Distribution monitors (volume, null-rate, value drift) exist, not just success/failure
 - [ ] Data contracts and compatibility tests are present
 - [ ] Ownership and runbook are clear

package/skills/roles/debugger.md

@@ -57,6 +57,15 @@ Load this before drafting. These are the failure modes that separate strong role
 **Why it fails**: the same bug returns in six months, silently.
 **Counter-move**: add a test that fails against the broken code and passes against the fix. Keep it.
 
+## Methodology
+
+Root cause is found by building a causal chain, not by guessing:
+
+- **Earliest anomaly first**, then work *forward* along cause→effect. The first error in the log is usually an effect; trace upstream to the first place reality diverged from expectation.
+- **Five whys, but each "why" is a tested link, not a story.** "Null pointer → the cache was empty → the warmer never ran → its trigger was disabled → the deploy disabled it." Every arrow must be confirmed by evidence (a log, a value, a repro), or the chain is fiction.
+- **Distinguish the trigger from the root cause** (as in a postmortem): the input that set it off vs. the system condition that let that input cause harm. Fix the root cause; note the trigger.
+- **Stop at the deepest link you can change.** Going past the actionable cause into "why does the language allow this" is rumination; stopping at the first symptom leaves the bug. The root cause is the earliest link whose change prevents recurrence.
+
 ## Self-check before shipping
 
 - [ ] Cause stated in one sentence before the fix

package/skills/roles/designer.accessibility.md

@@ -37,8 +37,18 @@ Additional failure modes on top of the designer core.
 **Why it fails**: triggers vestibular disorders; drives users away.
 **Counter-move**: honor `prefers-reduced-motion`. Provide pause controls for any auto-playing content.
 
+## Methodology
+
+Automated checks (axe, Lighthouse) catch perhaps a third of WCAG issues; the rest are found by use, not by scan:
+
+- **Test with a real screen reader**, not just the accessibility tree — drive the flow with VoiceOver or NVDA and confirm the announced order, labels, and state changes make sense aurally. The DOM can be valid while the spoken experience is incoherent.
+- **Keyboard-only, full task**: complete the whole task with no pointer. Watch focus order, visible focus, and focus traps (modals must trap and restore focus). A reachable control that focus never lands on is unreachable.
+- **Cover the four POUR principles** (Perceivable, Operable, Understandable, Robust) against WCAG 2.x AA — not just contrast and alt text. Understandable includes cognitive load: clear language, predictable behavior, forgiving error recovery.
+- **Test at 200% zoom and with reduced-motion set**; reflow and motion are where "looks accessible" breaks.
+
 ## Self-check before shipping
-- [ ] Keyboard-only path tested for every interactive element
-- [ ] Screen-reader output verified
+- [ ] Keyboard-only path completes the full task; focus order, visible focus, and traps checked
+- [ ] Screen-reader output verified by listening (VoiceOver/NVDA), not just the a11y tree
+- [ ] WCAG 2.x AA across POUR, including cognitive load — not only contrast/alt text
+- [ ] Tested at 200% zoom and with reduced-motion
 - [ ] Semantic HTML first; ARIA only where needed
-- [ ] Reduced-motion path exists and is tested

package/skills/roles/designer.md

@@ -58,8 +58,18 @@ Load this before drafting. These are the failure modes that separate strong role
 **Why it fails**: the product feels inconsistent even when individual screens are fine. Engineering cannot implement cleanly.
 **Counter-move**: name the tokens. space, color, type, radius, motion. before designing. Use them.
 
+## Methodology
+
+Design at the system level, not the screen level:
+
+- **Compose, don't draw.** Build from tokens → primitives → components → patterns (atomic design): a screen is an assembly of reused components, not a bespoke canvas. A new one-off where a component exists is debt; a new component should earn its place by appearing in ≥2 contexts.
+- **States are part of the component, not an afterthought.** Each component specifies its empty, loading, error, disabled, and populated states up front — the happy state alone is an incomplete design.
+- **Tokens carry meaning.** Name tokens by role (`color.text.danger`), not by value (`red-600`), so a theme or rebrand changes one definition, not every usage.
+- **Maturity check**: ad-hoc styles → shared components → a governed design system with usage docs and contribution rules. Name the current rung; "we have a component library" with widespread one-offs is rung two.
+
 ## Self-check before shipping
 
+- [ ] New UI composed from existing tokens/components; new components justified by reuse
 - [ ] Visual direction is explicit, not default
 - [ ] Empty / loading / error states designed as first-class
 - [ ] Primary actions visible at rest, not hover-gated

package/skills/roles/engineer.platform.md

@@ -42,8 +42,16 @@ Additional failure modes on top of the engineer core.
 **Why it fails**: platform surface area compounds blast radius. one leaked token touches every repo.
 **Counter-move**: treat platform secrets as production secrets. Rotate, scope-minimize, and audit.
 
+## Methodology
+
+**IaC maturity.** Infrastructure should climb a ladder: manual → scripted → declarative (Terraform/Pulumi) → declarative + policy-as-code + drift detection. The rung that matters is the last: state is reconciled (no manual console changes survive) and drift between declared and actual is detected and alerted, not discovered during an incident. Name the current rung honestly; "we have some Terraform" alongside hand-edited resources is rung two, not four.
+
+**Supply chain.** Every build emits an SBOM (software bill of materials) so a new CVE can be answered with "are we affected, where" in minutes, not a manual audit. Pin and verify dependencies (lockfiles, checksums, ideally signed provenance), and run the dependency/CVE audit in CI as a gate, not a report. The platform's blast radius is every repo it serves — a compromised build step is the highest-leverage attack.
+
 ## Self-check before shipping
 - [ ] First consumer migrated and measured
+- [ ] Infra is declarative with drift detection; no surviving manual changes
+- [ ] Build emits an SBOM; dependencies pinned/verified; CVE audit gates CI
 - [ ] Deprecation window respected for any breaking change
 - [ ] Failure diagnostics and artifacts preserved
 - [ ] Build-time and cost deltas measured

package/skills/roles/operator.md

@@ -69,10 +69,19 @@ Load this before producing operator output. SRE, ops, release, and durable-knowl
 
 **Why it fails**: no systematic comparison between planned work (documents) and actual work (tickets). Gaps accumulate silently until delivery dates slip.
 
-**Counter-move**: run periodic gap analysis: query strategy/PRDs/RFCs from knowledge base, compare with Jira tickets via search, identify missing tickets. Create补缺 tickets automatically (or queue for approval). Treat "execution gap" as a first-class risk signal.
+**Counter-move**: run periodic gap analysis: query strategy/PRDs/RFCs from knowledge base, compare with Jira tickets via search, identify missing tickets. Create gap-filling tickets automatically (or queue for approval). Treat "execution gap" as a first-class risk signal.
+
+## Methodology
+
+Sequencing work is a calculation, not a vibe:
+
+- **Critical path.** Build the dependency graph of the work, then find the longest chain of dependent tasks — that chain, not the total task count, sets the earliest finish. Shortening anything off the critical path does not move the date; shortening the critical path does. Re-find it after every scope change, because it moves.
+- **Slack.** Tasks off the critical path have slack (they can slip without moving the date). Spend attention proportional to slack: a one-day slip on a zero-slack task is a schedule slip; the same slip with five days of slack is noise.
+- **Resource leveling.** Two critical tasks needing the same owner cannot truly run in parallel — leveling for the real constraint (people, environments, review capacity) usually extends the path the naive graph hid. Sequence to the actual bottleneck.
 
 ## Self-check before shipping
 
+- [ ] Critical path identified; the date is driven by it, not by task count
 - [ ] Each runbook step names its purpose and expected output
 - [ ] Rollback is a tested, first-class plan with trigger criteria
 - [ ] Every alert is actionable; non-actionable signals moved to dashboards

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. -->