@geraldmaron/construct 1.1.0 → 1.2.0

package/skills/docs/research-workflow.md

@@ -1,56 +1,73 @@
 ---
 name: docs-research-workflow
-description: "Use when: the user asks to research a topic, investigate a question, or gather evidence for a decision."
+description: "Use when: cx-researcher must investigate external facts — CVEs, APIs, market data, regulations, or vendor behavior."
 inputs: [research-question]
 artifactType: research-brief
+toneDefault: direct
+toneAllowed: [direct]
+verificationBar: "Every load-bearing claim cites a verifiable primary source; label inference confidence; satisfy template structure requirements."
 ---
-# Research Workflow
+# External Research Workflow
 
-Use when: the user asks to research a topic, investigate a question, or gather evidence for a decision.
+Use when: cx-researcher investigates **external** facts — not user interviews or codebase exploration. For user evidence use `docs/user-research-workflow`; for repo exploration use `docs/codebase-research-workflow`.
 
 Follow [rules/common/research.md](../../rules/common/research.md) as the default policy.
 
 ## Steps
 
 1. **Clarify the question**: one specific, falsifiable question the research must answer.
-2. **Apply recency discipline**: always search from the most recent year backward. For fast-moving domains (AI tools, security, market data), treat anything older than 12 months as presumptively stale unless a newer source confirms it is still accurate.
-3. **Check internal evidence first**: search `.cx/research/`, `.cx/knowledge/`, `docs/prd/`, `docs/meta-prd/`, ADRs, runbooks, and ingested artifacts before going external.
-4. **Choose the research path and starting point** by domain:
+2. **Apply recency discipline**: search from the most recent year backward. For fast-moving domains, treat sources older than 12 months as presumptively stale unless confirmed.
+3. **Check internal evidence first**: `.cx/research/`, `.cx/knowledge/`, PRDs, ADRs, runbooks before going external.
+4. **Choose authoritative starting points** (external primary only):
 
-   | Domain | Authoritative starting points |
+   | Domain | Starting points |
    |---|---|
-   | AI tools / LLM behavior / multi-agent | arXiv (cs.AI, cs.SE, cs.CL), ACL Anthology, conference proceedings (NeurIPS, ICML, ICLR, HICSS) |
-   | Developer tools / IDE / adoption | Stack Overflow Developer Survey, JetBrains Developer Ecosystem Report, GitHub blog, editor changelogs |
-   | Security / CVEs / supply chain | NVD, GitHub Security Advisories, OWASP, vendor security blogs (Google Project Zero, Microsoft Security), ProjectDiscovery |
-   | Market data / ARR / adoption | Primary company announcements, SEC filings, then TechCrunch/Bloomberg citing company sources |
-   | Cloud / API / SDK / version | Official vendor docs for exact version, changelog, migration guide |
-   | Regulatory / compliance / privacy | Primary regulation text, then official agency guidance |
-
-5. **Use a source hierarchy**:
-   - Primary: official docs, exact-version API references, standards, source code, peer-reviewed papers
-   - Secondary: changelogs, migration guides, maintainer issue comments, release notes
-   - Tertiary: blogs/forums/Q&A only to locate primaries: never cite tertiary alone for a load-bearing claim
-6. **Verify every URL**: fetch each URL cited and confirm it resolves and matches the cited claim. Mark unconfirmed URLs as `[unverified]`.
-7. **Structure findings** using the template from `get_template("research-brief")`: resolves `.cx/templates/docs/research-brief.md` (override) then `templates/docs/research-brief.md` (shipped)
-8. **Write to `.cx/research/{topic-slug}.md`**: cx-docs-keeper owns this
-9. **Reference the research doc** in the requesting agent's output (link by path)
+   | AI / LLM / multi-agent | arXiv, ACL Anthology, NeurIPS/ICML/ICLR proceedings |
+   | Security / CVEs | NVD, GitHub Security Advisories, OWASP, vendor security blogs |
+   | Market / adoption | SEC filings, company announcements, then analyst reports citing primaries |
+   | Cloud / API / SDK | Official vendor docs for exact version, changelog, migration guide |
+   | Regulatory | Primary regulation text, official agency guidance |
 
-## Verification bar
+5. **Source hierarchy**: primary → secondary → tertiary (tertiary never alone for load-bearing claims).
+6. **Verify every URL** before citing. Mark unconfirmed as `[unverified]`.
+7. **Tone**: resolve from artifact manifest (`direct`). See `specialists/tone-profiles.json`.
+8. **Structure** with `get_template("research-brief")`; write to `.cx/research/{topic-slug}.md`.
+9. **Reference** the research doc in the requesting agent's output.
+
+## Distribution (publish pipeline)
+
+After the brief is written, **validate then publish** — the release gate is enforced by default:
+
+```bash
+node bin/construct artifact validate .cx/research/{topic-slug}.md --type=research-brief
+node bin/construct tools detect --json
+node bin/construct publish .cx/research/{topic-slug}.md --strict \
+  --demo=resource-guard-rails \
+  --dashboard-demo=cockpit-tour
+```
+
+Do **not** publish without a passing validate. Do **not** use `--no-gate` in demos or ship paths.
 
-- Every load-bearing claim must cite a verified source path, URL, or document reference.
-- Record publication date, version, or access date for each source. If no date is available, state `[undated]` and treat confidence as `low`.
-- Fetch and confirm every URL before including it in a committed document.
-- Separate observation from inference: label each finding's confidence as `high`, `medium`, or `low`.
-- Name contradictions and unresolved gaps.
-- Prefer two independent sources per load-bearing claim unless one authoritative primary source is sufficient.
-- State the strongest counter-evidence when one exists.
+Optional frontmatter in the brief:
 
-## File naming
-- Topic slug: lowercase, hyphens, no spaces: e.g., `firebase-auth-v9-migration.md`
-- Date prefix for time-sensitive research: `2026-04-release-comparison.md`
+```yaml
+publish:
+  demo: resource-guard-rails
+  dashboardDemo: cockpit-tour
+```
 
-## When research feeds a decision
-→ Also create `.cx/decisions/ADR-{NNN}-{slug}.md` referencing the research doc
+**Community patterns (do not hand-roll):**
+
+- **Figures in PDF**: fenced ` ```d2` / ` ```mermaid` blocks rendered at export time via vendored [pandoc-ext/diagram](https://github.com/pandoc-ext/diagram) (`construct export --figures` or `construct publish`).
+- **Terminal demos**: shipped `.tape` files under `templates/demos/tapes/`; project overrides in `.cx/demos/tapes/`; regenerate with `construct demo record <name>` or CI `charmbracelet/vhs-action`.
+- **Dashboard demos**: Playwright `e2e/demo/*.spec.ts` with `video: on` in `apps/dashboard`; run via `construct demo dashboard:<name>`.
+
+Install toolchain once: `brew install d2 graphviz pandoc typst vhs` and `npm install -g @mermaid-js/mermaid-cli`. Playwright: `cd apps/dashboard && npm install && npx playwright install chromium`.
+
+Do **not** claim PDF/demo done until `construct tools detect` reports ready or `--strict` publish succeeds.
+
+## Verification bar
 
-## When research feeds a PRD
-→ Reference it in the PRD's References section
+- Two independent sources per load-bearing claim unless one authoritative primary suffices.
+- Admiralty grades on every source. Counter-evidence named when it exists.
+- cx-researcher must **not** answer UX preference questions or infer codebase behavior without reading code.

package/skills/docs/runbook-workflow.md

@@ -3,6 +3,7 @@ name: docs-runbook-workflow
 description: "Use when: creating operational procedures for services, alerts, or recurring operations."
 inputs: [service, incident]
 artifactType: runbook
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Runbook Workflow
 

package/skills/docs/strategy-workflow.md

@@ -3,6 +3,7 @@ name: docs-strategy-workflow
 description: "Use when: the user asks about product direction, strategic bets, what to prioritize, whether a signal aligns with strategy, or wants to update the strategy."
 inputs: [signal, decision-context]
 artifactType: strategy
+verificationBar: "Every load-bearing claim cites a verifiable source; label inference confidence; satisfy template structure requirements."
 ---
 # Strategy Workflow
 

package/skills/docs/user-research-workflow.md

@@ -0,0 +1,40 @@
+---
+name: docs-user-research-workflow
+description: "Use when: cx-ux-researcher synthesizes user evidence — interviews, support tickets, session replay, surveys, or field notes."
+inputs: [user-research, interview-data]
+artifactType: evidence-brief
+toneDefault: pedagogical
+toneAllowed: [pedagogical, direct, friendly]
+verificationBar: "Observed behavior weighted over self-report; sample size stated; no invented quotes."
+---
+# User Research Workflow
+
+Use when: cx-ux-researcher gathers or synthesizes **user** evidence. Do not use for CVE lookups, API version facts, or repo structure — use `docs/research-workflow` (cx-researcher) or `docs/codebase-research-workflow` (cx-explorer) instead.
+
+Follow [rules/common/research.md](../../rules/common/research.md) and call `get_skill("roles/researcher.ux")` before drafting.
+
+## Steps
+
+1. **Clarify the user question**: who specifically, what behavior or friction, falsifiable claim.
+2. **Check internal user evidence**: `.cx/knowledge/external/`, customer profiles, evidence briefs, support exports, ingested transcripts.
+3. **Choose source classes** (user-primary):
+
+   | Source | Class | Notes |
+   |---|---|---|
+   | Interview transcript | primary | Direct quotes with participant id, not name |
+   | Support ticket / chat | primary | Link ticket id; preserve ambiguity |
+   | Session replay / analytics | primary | State segment and timeframe |
+   | Survey (structured) | secondary | Note response rate and bias |
+   | Sales / CS summary | secondary | Trace to underlying tickets when possible |
+
+4. **Sampling**: state segment, N, recruitment method. Behavioral claims need ≥5 per segment unless exploratory (flag as low confidence).
+5. **Validity**: name the weakest validity threat (internal/external/construct/conclusion) per `roles/researcher.ux` — that threat is where the finding is most likely wrong.
+6. **Inter-rater reliability**: when themes are coded from qualitative data, two coders code a sample independently; report agreement (or Cohen's κ when N permits). Persistent disagreement means the codebook is unfinished — fix the codebook before shipping themes.
+7. **Tone**: default `pedagogical`; override via `.cx/brand-voice.json` if present.
+8. **Output**: `get_template("evidence-brief")` or `signal-brief` when threshold not met; store under `.cx/knowledge/internal/evidence-briefs/`.
+
+## Verification bar
+
+- No invented customer names, quotes, or ticket ids.
+- Findings describe problems, not prescribed UI solutions.
+- cx-ux-researcher must **not** cite blog posts for API version or security claims.

package/skills/operating/orchestration-reference.md

@@ -52,7 +52,7 @@ Do not duplicate skill internals inside agent prompts. Reference the relevant sk
 Every producer→consumer pair has an explicit contract in `specialists/contracts.json`, loaded via `lib/specialist-contracts.mjs`. Specialists call the MCP tool `agent_contract` at the start of a handoff to see:
 
 - `input.mustContain`: fields the packet must carry
-- `input.schema`: JSON schema (when applicable) from `lib/schemas/`
+- `input.schema`: JSON schema (when applicable) from `lib/contract-schemas/`
 - `preconditions`: what must be true before work starts
 - `output.schema` / `output.shape`: expected return shape
 - `postconditions`: what must be true before marking DONE

package/skills/roles/architect.md

@@ -58,6 +58,10 @@ Load this before drafting. These are the failure modes that separate strong role
 **Why it fails**: the team now owns the maintenance of both the product and a worse version of an existing tool.
 **Counter-move**: survey existing tools honestly. If building, articulate exactly what the existing tools fail to do.
 
+## Methodology
+
+**Experimental design (cx-rd-lead).** Before committing build capacity to an R&D bet, state the falsifiable hypothesis, the minimum detectable effect size that would change the decision, and the power analysis: given expected variance and α, what N (users, runs, or samples) is required to detect that effect? An under-powered study that returns "no difference" is inconclusive, not negative evidence — name the required N and whether the planned study meets it. Report effect sizes with confidence intervals, not only p-values or pass/fail.
+
 ## Self-check before shipping
 
 - [ ] Requirements are stated before tech choices
@@ -68,3 +72,4 @@ Load this before drafting. These are the failure modes that separate strong role
 - [ ] Scaling assumptions are named and tied to the business plan
 - [ ] Migration path is explicit with phases and rollback points
 - [ ] Build-vs-buy is justified when building
+- [ ] R&D bets state minimum detectable effect size and required N (power analysis)

package/skills/roles/operator.docs.md

@@ -37,6 +37,10 @@ Additional failure modes on top of the operator core.
 **Why it fails**: rot is guaranteed; questions route to Slack instead of the doc.
 **Counter-move**: every doc declares an owner (person or role). Ownership appears in the header.
 
+## Methodology
+
+**Per-doc-type tone from the manifest.** Before editing a typed artifact, resolve tone from `specialists/artifact-manifest.json` (`toneDefault`, `toneAllowed`) and the profile definitions in `specialists/tone-profiles.json`. Projects override per type via `.cx/brand-voice.json`. `construct artifact validate <path> --type=<type>` reports the resolved tone — match it unless the user explicitly requests a different allowed profile.
+
 ## Self-check before shipping
 - [ ] Last-reviewed date present and fresh
 - [ ] One canonical source per concept; duplicates redirect

package/skills/routing.md

@@ -120,7 +120,9 @@ Read the matching skill file before responding when the user's request matches t
 | Trigger Keywords | Skill File | Description |
 |---|---|---|
 | init docs, create docs structure, set up documentation, docs scaffold, documentation init | `skills/docs/init-docs.md` | Initialize required project-state docs and documentation structure |
-| research X, investigate X, find evidence, gather evidence | `skills/docs/research-workflow.md` | Research workflow: question to .cx/research/ file |
+| research X, investigate X, find evidence, gather evidence, CVE, vendor docs, market data | `skills/docs/research-workflow.md` | External research workflow (cx-researcher) |
+| user research, interview synthesis, support tickets, UX evidence, field notes | `skills/docs/user-research-workflow.md` | User research workflow (cx-ux-researcher) |
+| map codebase, explore repo structure, dependency graph, hot path | `skills/docs/codebase-research-workflow.md` | Codebase research workflow (cx-explorer) |
 | product intelligence, customer notes, field notes, product signals, customer profile, evidence brief, signal brief, backlog proposal | `skills/docs/product-intelligence-workflow.md` | Product Intelligence workflow: evidence to product artifacts |
 | strategy, product strategy, strategic bet, non-bet, north star, time horizon, competitive positioning | `skills/docs/strategy-workflow.md` | Product strategy: read, update, and reason about the strategy store |
 | ingest evidence, ingest customer notes, ingest Slack thread, ingest support ticket, normalize field notes | `skills/docs/evidence-ingest-workflow.md` | Evidence ingest workflow: raw source to .cx/knowledge/ |
@@ -129,7 +131,7 @@ Read the matching skill file before responding when the user's request matches t
 | create Jira proposal, update Linear, backlog proposal, issue proposal | `skills/docs/backlog-proposal-workflow.md` | Backlog proposal workflow: approval-gated issue tracker changes |
 | record this decision, create an ADR, architecture decision | `skills/docs/adr-workflow.md` | ADR workflow: decision to docs/adr/ file |
 | write a runbook, document this operation, operational procedure | `skills/docs/runbook-workflow.md` | Runbook workflow: operation to docs/runbooks/ file |
-| init project, new project setup, join project, set up doc structure | `skills/docs/init-project.md` | Project initialization via construct init-docs |
+| init project, new project setup, join project, set up doc structure | `skills/docs/init-project.md` | Project initialization via `construct init --docs-preset=*` |
 
 ## Routing Rules