Dossier

Dossier

Structured research producing actionable reports with ranked recommendations, cited sources, and optional decision ballots. Works for any domain — tech, travel, health, policy, finance, art.

Workflow: SCOPE → GATHER → EVALUATE → SYNTHESIZE → DELIVER

0. Preflight — verify the request is actionable

Before starting research, confirm all three:

1. Specific — what to investigate is bounded: a named topic, a concrete comparison, or a clear question. "Look into the X space generically" fails this.
2. Unambiguous — contested terms are defined by context. If the request uses a word with multiple plausible meanings and context doesn't resolve which, flag it.
3. Well-understood — you can state the objective back to the operator in 1–2 sentences without hedging. If you'd have to pad with "I think you mean…" or "depending on what you want from this…", you don't understand it yet.

If one or more checks fail, ask before starting. A dossier built on unclear objectives wastes more research time than the clarifying turn costs. Batch questions; offer choices where reasonable; skip the obvious.

If all three check out, proceed directly to SCOPE. Do not ask just to perform diligence — the bar is "the answer isn't obvious from context," not "I want to be extra sure."

1. SCOPE

• Type: comparison, evaluation, or investigation?
• Requirements: R1-Rn with weights (Critical/High/Medium) — for comparisons
• Selectivity: 5-8 options, not a laundry list
• Decision model (when a choice is being made): note who decides, by when, and how — record in the Key Facts box before GATHER.
• Sources: consult ${CLAUDE_SKILL_DIR}/references/sources-by-domain.md
• Output folder: Check existing research/ directories first — if one matches the current topic, add to it rather than creating a new folder. Ask the user when unsure. Only create research/YYYY-MM-DD-slug/ for genuinely new topics.

2. GATHER

Dispatch parallel subagents scaled to complexity:

| Complexity | Strategy | |-----------|----------| | Quick (1-2 options) | Sequential, no subagents | | Standard (3-6) | 1 Explore agent per option | | Deep (6+ or broad) | 1 per option + 3 fact-checkers post-synthesis | | Architecture decision | 3 Plan agents with named perspectives |

Each agent returns structured findings with URLs for every claim. Check /last30days first for topics with social signal (consumer, OSS). Skip for B2B, academic, niche. Pivot to WebSearch if suffix on the date line, no "first draft framed X / corrected after feedback" phrasing in the body. When you receive corrections mid-session, **rewrite** the affected lines as plain present-tense facts — don't append a changelog. Keep a point if it is load-bearing for the conclusion, but state *why it matters* (X was considered because Y), not *that it was added later* (edited to also consider X because Y was raised). Document history belongs in commit messages and the sessionlog. (Deliberate dated addenda on already-published dossiers are a different case and out of scope here.) Reviewed via ${CLAUDESKILLDIR}/references/review-checklist.md` (single-current-version item).

Ballot (when decisions happen async — reviewed over chat, on a PR, after the session ends): use the ballot skill. Works for multi-reviewer panels and single async deciders alike. Template at skills/ballot/templates/ballot-per-reviewer.md; conventions at skills/ballot/SKILL.md.

5. DELIVER

Before committing, run the reviewer checklist at ${CLAUDE_SKILL_DIR}/references/review-checklist.md against the finished dossier. It covers preflight evidence, citation integrity, dated-claim freshness, section ordering, source bias flagging, hyperlink density, selectivity, and Key Facts box accuracy. The mechanical gate (ballot-filename) fires automatically on Write/Edit via the PostToolUse hook — exit 2 feeds stderr back to Claude — but most review concerns need human or judgement-capable model review, not pattern matching. Once the checklist passes:

• Commit dossier folder (D: intention per commit-notation).
• Do NOT end the session — stay available for follow-ups, iterations, or additional dossiers.

Output Convention

research/YYYY-MM-DD-slug/
├── DOSSIER-Title-Words-YYYY-MM-DD.md           # Main report
├── DOSSIER-Title-Words-BALLOT-Max.md           # Optional: one per decider
├── DOSSIER-Title-Words-BALLOT-Patrick.md       # Optional: one per decider (multi-reviewer case)
├── DOSSIER-Followup-Title-YYYY-MM-DD.md        # Follow-up dossiers in same folder
└── (attachments — rare)

Location: workspace research/ for standalone; projects/{name}/research/ for project-specific.

Multiple dossiers per folder is expected.

Gates (hooks)

One mechanical gate runs PostToolUse on Write|Edit through .claude-plugin/hooks/dossier-hook-dispatcher.sh. Exit 2 pipes stderr back to Claude. Alerting-level — the file is already on disk when it fires; a motivated agent can ignore. PreToolUse rigor is future work.

| Gate | Fails on | |------|----------| | ballot-filename.sh | Ballot file not matching DOSSIER--BALLOT-.md (owned by the ballot skill) |

Everything else is reviewed by checklist, not by grep. Earlier iterations shipped grep-gates for citation integrity, forbidden words, section ordering, dated claims, and ballot cover-block archaeology — a 2026-04-18 polish pass removed them after they proved overfit to the a11y-extension session. dossier-framing-declared.sh was removed in the 2026-04-18 preflight-gate pass: the framing-mode convention it enforced doesn't generalize across dossier styles. See ${CLAUDE_SKILL_DIR}/references/review-checklist.md.

Common Mistakes

| Mistake | Fix | |---------|-----| | Orphan citations | Reviewed in the checklist (citation-integrity item) — every inline reference should match a §Sources entry | | Glossary at the back of the dossier | Glossary first (read-support); Sources last (trust-support) | | Dates treated as static | Reviewed in the checklist (dated-claim-freshness item) — re-verify each | | Exhaustive list, not selective | Set selectivity in SCOPE ("5-8, not all"); reviewed in the checklist | | Generic recommendations | Tailor to THIS user's context and infrastructure | | Bare product names without URLs | Hyperlink every entity on first mention | | Same source categories every time | Adapt to domain (see references/sources-by-domain.md) | | Narrating edit history in the body | Collapse to one current version; recast research-driven points as facts, not as a changelog. Reviewed in the checklist (single-current-version item) | | Ending or re-starting session after delivery | Stay open — auto-compact handles context |

For ballot-specific mistakes (anti-options, pre-ticked checkboxes, cover-block archaeology, single-file two-column ballots, reconciliation placement), see skills/ballot/SKILL.md §Common Mistakes.

Related Skills

| Skill | Integration | |-------|-------------| | ballot | Extracted decision-ballot format. SYNTHESIZE hands off when a decision surface is needed. | | last30days | Social signal for consumer/OSS topics | | commit-notation | D: prefix for dossier commits | | bye | Sessionlog at session end (NOT after each dossier) | | challenge-the-plan | Optional: interview-style requirements refinement |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: eins78
• Source: eins78/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.