research-analysis

name	research-analysis
description	Create, maintain, and validate the per-package `analysis.html` page (Rules + Insight). Use this skill whenever the user types /research-analysis, asks to initialize / scaffold / lint an analysis page, asks to add a distilled rule or a deep-analysis insight to a package, asks to summarize an insight into a rule, or asks to embed a visualization (bar chart, heatmap, threshold chart, admission matrix) into an insight sub-block. Project-agnostic. Hard requirement: the dashboard at <cwd>/research_html/ must already exist (run /research-dashboard first) and the target package must already exist (run /research-package first). Analysis is the single home for the lessons distilled from a package's results — Rules are generalized constraints future packages must obey; Insights are the mechanism-level diagnostics that justify those rules. Both blocks are manual-only and never auto-populated from results, tracker, or inventory.
argument-hint	<subcommand: init | add-insight | add-rule | lint> [args]
allowed-tools	Bash(*), Read, Edit, Write, Glob, Grep

Research Analysis

Purpose

Own the per-package analysis.html page so its contract stays invariant across packages. The page captures the deep analysis of a package's results — the why behind the verdicts on results.html (Insight block) — and the generalizable design lessons future packages must obey (Rules block). The skill provides four crisp operations: init, add-insight, add-rule, lint.

Authority

Authority order, highest first:

1. The user's invocation prompt and any explicit --<flag> overrides.
2. Trust rules T1–T24 in <root>/rules/trustworthy-research-rules.html.
3. Form rules R1–R18 in <root>/rules/html-rules.html.
4. The two-block contract in this skill (below).
5. references/viz-templates.md — reusable visualization snippets with the canonical color palette.

Boundary (binding)

• results.html owns what happened — result-gate table, validity chips, per-experiment cards, claim analysis. Mechanically populated; inventory-coupled; lint-gated.
• analysis.html owns why it happened (Insight) and what future packages must not repeat (Rules). Hand-curated only. No auto-population. No propagate_facts hook. No methodsTried writes.
• Rules in analysis.html are NOT methodsTried[] in data/research-packages.js. methodsTried is a per-experiment verdict record consumed by learnings.html. Rules are generalized, transferable design constraints consumed by humans+agents to avoid repeating mistakes. The two co-exist and answer different questions.
• Stage order on the package nav: overview → plan → implementation → results → analysis → tracker → docs. Analysis sits between results and tracker (the chosen-route / next-action decision is folded into tracker.html#chosen-route).
• File writes to analysis.html (and removals) go through /research-op (--target rule with level=package, kind=lesson for Rules; --target analysis-insight for Insights); the footer <time> timestamp is bumped automatically by the handler, so no separate call is needed. This skill owns the editorial decision (when a rule is warranted, what counts as an insight); /research-op owns the store and the paint (the registry row, where to insert, what shape, lint compliance). Lint (scripts/lint_analysis.py) stays in this skill.

Pre-flight checks

1. The dashboard exists:

   test -f <cwd>/research_html/index.html && test -f <cwd>/research_html/data/research-packages.js && echo dashboard-ok
   

2. The target package exists:

   test -f <cwd>/research_html/packages/<id>/index.html && echo package-ok
   

3. The dashboard JS registers analysis in STAGE_PAGES (<root>/assets/research.js) and the CSS holds the per-page override (body[data-page="analysis"] #rules { grid-template-columns: 1fr; }). The dashboard skill ships both — if either is missing, the dashboard is out of date; ask the user to re-run /research-dashboard rather than patching the dashboard from this skill.

If any check fails, stop and tell the user what to run first; do not silently scaffold the prerequisite.

Two-block contract (binding)

analysis.html carries exactly two top-level sections, in this order:

1. Rules (<section id="rules" data-section="rules">) — a numbered list, one <li> per rule.
2. Insight (<section id="insight" data-section="insight">) — a stack of collapsible <details> sub-blocks, one per analyzed experiment, phase, or theme.

The rules block sits above the insight block because rules are the high-density take-away; the insight block is the supporting evidence.

Rules block — strict format

• The block is a paint of the unified rules registry (data/rules.js, rows with level=package, kind=lesson, status=ACTIVE for this package). Never hand-edit the <ol>; the research-op rule handler regenerates it on every rule insert/update/delete.
• Container: <ol class="rules-list" data-list="rules">.
• Each rule paints as one <li class="card-text" id="rule-<slug>">…</li>.
• The slug is kebab-case and unique within the package (e.g. rule-non-binding-precondition).
• The row's text is plain natural-language prose, written so a human reader and an agent both understand and can apply the rule without re-opening the linked insight. Embed the binding numbers, thresholds, and named subjects inline; name the justifying insight slug in the row's rationale.
• No <strong>, <b>, or other emphasis on the rule itself. Plain sentences, not imperatives in bold.
• Add a rule only when a result clearly warrants a generalizable lesson, not on every run. The Rules block can stay empty for the whole life of a package.

When the page is initialized and no rule exists yet, render a placeholder:

<li class="card-text"><em>No rules recorded yet.</em></li>

Remove the placeholder when the first real rule lands.

Insight block — strict format

• Container: <div class="insight-body" data-block="insight-body">.
• Each insight is a <details class="insight-subblock" id="insight-<slug>"> card. Always <details> (closed); never <details open>.
• The <summary> is the clickable title bar (one line, no nested elements).
• The <details> body is a single inner <div> with consistent padding; inside it: narrative paragraphs (<p class="card-text">), optional <h4> sub-headings, inline-styled visualizations from references/viz-templates.md, and one caption paragraph immediately after each visualization.
• Every visualization caption is a <p class="card-text" style="font-size:0.88rem; color:#555;"> paragraph that starts with <em>Reading:</em> and explains what the reader should take away.
• Closed by default (binding): every insight sub-block renders closed. The summary line is the index; readers click to expand. This rule supersedes any earlier guidance that said the most recent insight should be <details open>.
• Each sub-block has a stable deep-link anchor (id="insight-<slug>") so rules can cite it.
• Manual update only. Never auto-populate an insight from results.html, tracker.html, or data/research-packages.js.

When the page is initialized and no insight exists yet, render a placeholder:

<p class="card-text"><em>No insight content yet.</em></p>

Remove the placeholder when the first real insight lands.

Visualization palette (binding)

Visualizations are inline-styled HTML/CSS only — no external charting libraries, no <script> blocks, no canvas. Use the colors below. Every visualization is followed by exactly one caption paragraph.

Role	Color	Notes
Card chrome (<details> border)	#d8dde6	1 px solid
Card chrome (<details> background)	#fafbfd	very light off-white
Card chrome (<summary> text)	#1f2a44	dark navy
Bar background	#eef	very light blue-gray
Bar border	#ccd	1 px solid
Neutral / baseline bar fill	#888	medium gray
Pass / improved bar fill	#4a8e63	medium green
Fail / regressed bar fill	#a14444	medium red
Threshold dashed line	#c33	2 px dashed
Pass chip bg / text / border	#dff5e3 / #0a5d24 / #b8e5c2	green chip
Fail chip bg / text / border	#fde2e2 / #7a1a1a / #f0b8b8	red chip
Heatmap gradient (best → worst)	#fbe0db → #f4ada1 → #e89486 → #c8593f → #a93527 → #8c2c1f → #691f15	seven discrete bands
Caption	font-size:0.88rem; color:#555;	always after a viz

See references/viz-templates.md for copy-paste-ready snippets of:

• threshold bar chart (one row per cell, vertical threshold line)
• before/after paired bar table (rowspan delta column)
• 2-D heatmap (e.g. G × p dose-response)
• single-axis dose-response bar chart (e.g. sibling-count tax)
• admission matrix (2-D pass/drop grid)

Operations

The skill has four subcommands. All are explicitly user-triggered; none run on a timer or as part of a fact-propagation cycle.

init <package-id>

Install the empty analysis.html page in the package and opt it into the package's inventory pages array.

python <skill-dir>/scripts/init_analysis_page.py \
  --root <cwd>/research_html \
  --package-id <YYYY-MM-DD-slug>

Behavior:

• Reads the package's existing name from data/research-packages.js.
• Writes <root>/packages/<id>/analysis.html from templates/analysis.html (refuses to overwrite unless --force).
• Adds "analysis" to the package's pages array in data/research-packages.js if not already present.
• Verifies (does not patch) that the dashboard ships:
  • analysis in STAGE_PAGES (in <root>/assets/research.js)
  • body[data-page="analysis"] #rules { grid-template-columns: 1fr; } in <root>/assets/research.css
  • Both ship from the research-dashboard skill — emit a warning with the patch command if absent.
• After init, every subsequent edit to analysis.html goes through /research-op (--target rule with kind=lesson for the Rules block, --target analysis-insight for the Insight block; this skill's add-rule and add-insight subcommands are thin wrappers around those).

add-insight <package-id> <slug> <title>

Append one new <details> sub-block to the Insight block. The agent then hand-edits the body. This skill delegates the file write to /research-op:

python skills/research-op/scripts/research_op.py \
  --pkg <package-id> --op insert --target analysis-insight \
  --payload '{"slug":"<slug>","title":"<title>","body":"<body html>"}'

/research-op writes the <details class="insight-subblock" id="insight-<slug>"> wrapper closed by default; the agent edits the inner body via Edit after the wrapper lands. Use templates/insight-subblock.html as the shape reference for that body. This skill no longer ships its own scaffolding script for insight additions.

Embed a visualization (the embed a bar chart / heatmap / … trigger): after the insight wrapper lands, open the matching snippet in references/viz-templates.md — threshold bar chart, paired before/after bar, 2-D heatmap, single-axis dose-response, or admission matrix — paste it into the insight body via Edit, recolor with the palette, and add the required <em>Reading:</em> caption paragraph immediately after it. No separate subcommand or script is involved.

This insert is only legal while the package category is in-progress; for terminal packages (success / fail) the analysis page is frozen and /research-op rejects the call — surface the rejection and ask the user before attempting a write.

add-rule <package-id> <slug>

Add one distilled rule. The rule lands as a typed row in the unified rules registry (data/rules.js, level=package, kind=lesson); /research-op repaints the Rules block <ol> from the registry in the same call — the page is a paint, never the store. The agent hand-crafts the prose; this skill delegates the write to /research-op:

python skills/research-op/scripts/research_op.py \
  --pkg <package-id> --op insert --target rule \
  --payload '{"level":"package","kind":"lesson","slug":"<slug>","title":"<short name>","text":"<rule prose>","rationale":"<which insight/verdict justifies it>","addedAt":"<YYYY-MM-DD>"}'

/research-op runs the rule-target Phase 2 validators (kebab-case slug, required fields, kind=lesson needs ≥1 finalized result-gate row) and either writes+repaints or rejects with the structured envelope. This skill no longer ships its own scaffolding script for rule additions.

For the summarize-an-insight-into-a-rule trigger: first read the target insight sub-block, distill the single generalizable lesson, then call add-rule with that prose and name the insight slug in rationale so the provenance stays traceable. There is no separate summarize subcommand — it is add-rule applied to an existing insight.

As with add-insight, this insert is only legal while the package category is in-progress; for terminal packages (success / fail) /research-op rejects the call — surface the rejection and ask the user before attempting a write.

lint <package-id-or-all>

Validate the contract on one package or all packages. Returns non-zero on violations.

python <skill-dir>/scripts/lint_analysis.py \
  --root <cwd>/research_html \
  [--package-id <id> | --all]

Checks per page:

• <body data-page="analysis" data-package-id="<id>"> is present and the id matches the directory.
• The two sections appear in order: #rules first, then #insight. No other top-level section between them.
• Every <li> inside <ol class="rules-list"> either is the No rules recorded yet. placeholder OR has id="rule-<slug>" with a kebab-case slug; painted slugs must match the registry's ACTIVE lesson rows in both directions (drift is an error).
• Every <li class="card-text" id="rule-*"> body contains no <strong> or <b> tag wrapping the rule itself (inline <em> for emphasis on a sub-clause is allowed; the lint checks only <strong>/<b>, not <em>).
• Every <details> inside <div class="insight-body"> has id="insight-<slug>", exactly one <summary>, and at least one <p class="card-text"> in its body.
• Every visualization (any element with style="…background:#…" that contains width: or sits inside a grid) is followed by a caption <p class="card-text" style="…0.88rem…color:#555…">.
• Every #rule-* Evidence link resolves to an #insight-* anchor that exists on the same page.
• Inventory check: the package's pages array in data/research-packages.js includes "analysis".
• Dashboard check: STAGE_PAGES in <root>/assets/research.js includes the analysis slot, and the #rules CSS override is present.

A clean lint exits 0 silently; violations are printed one per line with a file:line anchor where possible.

Update cadence (binding)

• Insight is updated only on explicit user instruction. If a user says "summarize the V0 results into an insight," that's an explicit instruction. If the agent is on a propagate_facts cycle, it never touches analysis.html.
• Rules are updated only when a result clearly warrants a generalizable lesson. Most experiments will not warrant a new rule. An insight without a rule is still useful; a rule without an insight to link is not allowed.
• When a rule is added, the linked insight must already exist on the page (the lint subcommand catches broken #insight-<slug> links).

Relationship to other skills

• /research-dashboard ships the global JS/CSS that registers the analysis page in the nav and fixes the 1-column layout for the Rules section. Re-run it after pulling the dashboard skill if either piece is missing.
• /research-package scaffolds the package shell. When --scope includes analysis (or is all), the scaffolder writes an empty analysis.html and adds analysis to the inventory pages array. The research-analysis skill then owns content updates on the page from that point on.
• learnings.html and data/research-packages.js methodsTried[] are owned by /research-package. Rules in analysis.html are a separate plane and never feed learnings.html.
• When an insight surfaces a durable field gap (a known unknown the field has not closed), register it in the project-level gap registry so it feeds the Context Pack's Open-gaps section — and link the idea/package that targets it with an ADDRESSES_GAP edge: research-op --op registry-add --target gap --payload '{"id":"G1","summary":"..."}' then --target edge --payload '{"from":"<idea-or-pkg>","to":"G1","type":"ADDRESSES_GAP","evidence":"..."}'. The gap registry is a separate plane from the manual analysis.html Rules; registering a gap never edits the analysis page.

Final response

After any subcommand, state:

• subcommand and arguments
• package id
• files written / patched
• inventory updates
• lint result (if applicable)
• one-line "next action" suggestion (e.g. "Add the first rule with /research-analysis add-rule …")

Apply the dashboard's output-classification rule: agent-only continuity notes go in a > blockquote.

Bundled resources

• templates/analysis.html — empty two-block scaffold rendered by init.
• templates/insight-subblock.html — one collapsible insight card, copy-paste boilerplate.
• templates/rule-bullet.html — research-op --target rule payload boilerplate for a package lesson row.
• references/viz-templates.md — five visualization patterns with the canonical color palette.
• scripts/init_analysis_page.py — init subcommand implementation.
• scripts/lint_analysis.py — lint subcommand implementation.