flonat-research 0.1.0

package/skills/shared/research-quality-rubric.md

@@ -0,0 +1,165 @@
+# Research Quality Rubric
+
+> Dimension-weighted scoring rubric for evaluating research papers and proposals.
+> Adapted from ScholarEval (Moussa et al., 2025, arXiv:2510.16234) with language
+> adjusted for social science, management, economics, and political economy.
+>
+> **When to load:** Any agent performing a structured research quality assessment.
+> **Complements:** `quality-scoring.md` (deduction-based) handles artifact polish;
+> this rubric handles substantive research quality across 8 dimensions.
+
+## Dimensions & Scales
+
+Each dimension is scored 1-5. Only 3/5/5 anchors are provided to keep the file lean.
+Score 2 = between Adequate and Weak; Score 1 = fundamental deficiencies.
+
+### 1. Problem Formulation & Research Questions (15%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | Novel contribution clearly situated in a gap; research questions are precise, falsifiable, and theoretically grounded; scope is well-bounded |
+| **4 Good** | Clear contribution with minor gap-articulation issues; questions are specific but could be sharper; scope is reasonable |
+| **3 Adequate** | Contribution exists but is vaguely stated; questions are broad or partially redundant; scope creep risk |
+
+- [ ] Gap in literature explicitly identified
+- [ ] Research questions are stated, specific, and answerable
+- [ ] Scope is bounded (what is in/out)
+- [ ] Contribution is distinguished from related work
+- [ ] Practical or theoretical relevance is articulated
+
+### 2. Literature Review (15%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | Comprehensive coverage of key streams; synthesises rather than lists; positions paper in ongoing debates; includes seminal and recent work |
+| **4 Good** | Covers main streams with minor omissions; mostly synthetic; positioning is clear |
+| **3 Adequate** | Covers basics but misses a stream or relies on dated sources; more descriptive than analytical |
+
+- [ ] Key theoretical streams identified and covered
+- [ ] Seminal works cited (not just recent)
+- [ ] Review is synthetic (themes/tensions) not a list
+- [ ] Competing perspectives acknowledged
+- [ ] Clear link from review to research questions
+- [ ] No major stream conspicuously absent
+
+### 3. Methodology & Research Design (20%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | Design is well-justified for the research questions; identification strategy is explicit; assumptions stated and defended; threats to validity addressed |
+| **4 Good** | Design fits questions; identification mostly clear; some assumptions implicit; validity threats partially addressed |
+| **3 Adequate** | Design is standard but justification is thin; identification strategy unclear; limited validity discussion |
+
+- [ ] Method choice justified for the research question
+- [ ] Identification strategy / causal logic explicit (if causal claims made)
+- [ ] Key assumptions stated
+- [ ] Threats to internal and external validity discussed
+- [ ] Robustness checks or sensitivity analyses planned
+- [ ] Replicability: sufficient procedural detail
+
+### 4. Data Collection & Sources (10%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | Data sources are well-suited, clearly described, and limitations acknowledged; sampling strategy justified; measurement validity established |
+| **4 Good** | Sources are appropriate with minor documentation gaps; sampling is reasonable; most measures validated |
+| **3 Adequate** | Sources are acceptable but convenience-driven; limited discussion of measurement validity or representativeness |
+
+- [ ] Data sources described (origin, timeframe, access)
+- [ ] Sampling strategy explained and justified
+- [ ] Key variables operationalised with clear measures
+- [ ] Data limitations acknowledged
+- [ ] Ethical considerations addressed (if human subjects)
+
+### 5. Analysis & Interpretation (15%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | Analysis follows logically from design; results interpreted carefully with appropriate caveats; alternative explanations considered; effect sizes contextualised |
+| **4 Good** | Analysis is sound; interpretation is mostly careful; some alternative explanations explored |
+| **3 Adequate** | Analysis is correct but mechanical; over-reliance on p-values; limited exploration of alternatives |
+
+- [ ] Analysis matches the stated methodology
+- [ ] Results interpreted with appropriate uncertainty
+- [ ] Alternative explanations considered
+- [ ] Effect sizes reported and contextualised (not just significance)
+- [ ] Limitations of the analysis acknowledged
+- [ ] Robustness checks reported
+
+### 6. Results & Findings (10%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | Findings directly address research questions; tables/figures are clear and self-contained; null or unexpected results reported honestly |
+| **4 Good** | Findings address questions with minor gaps; presentation mostly clear; negative results acknowledged |
+| **3 Adequate** | Findings partially address questions; tables overloaded or under-explained; selective reporting suspected |
+
+- [ ] Each research question has a corresponding finding
+- [ ] Tables and figures are well-labelled and interpretable
+- [ ] Null or unexpected results reported
+- [ ] Key numbers are precise (CIs, effect sizes, sample sizes)
+- [ ] No cherry-picking of specifications
+
+### 7. Scholarly Writing & Presentation (10%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | Argument flows logically; prose is concise and precise; structure supports the narrative; transitions between sections are smooth |
+| **4 Good** | Writing is clear with occasional redundancy; structure is sound; minor flow issues |
+| **3 Adequate** | Writing is understandable but verbose or disorganised in places; structure follows conventions but feels mechanical |
+
+- [ ] Abstract accurately summarises the paper
+- [ ] Logical flow from introduction to conclusion
+- [ ] No unnecessary jargon or undefined acronyms
+- [ ] Consistent terminology throughout
+- [ ] Within page/word limits (if applicable)
+
+### 8. Citations & References (5%)
+
+| Score | Indicators |
+|-------|-----------|
+| **5 Excellent** | All claims supported; no orphan citations or missing references; formatting consistent; bibliography is complete and accurate |
+| **4 Good** | Minor formatting inconsistencies; one or two unsupported claims; bibliography mostly complete |
+| **3 Adequate** | Several formatting issues; some claims lack support; bibliography has gaps or duplicates |
+
+- [ ] All factual claims have citations
+- [ ] No orphan `\cite{}` keys (all resolve)
+- [ ] Reference list matches in-text citations (no extras, no missing)
+- [ ] Formatting consistent with target venue style
+- [ ] DOIs or stable URLs present where appropriate
+
+## Weighted Scoring
+
+```
+Score = (0.15 x D1) + (0.15 x D2) + (0.20 x D3) + (0.10 x D4)
+      + (0.15 x D5) + (0.10 x D6) + (0.10 x D7) + (0.05 x D8)
+```
+
+| Range | Verdict | Interpretation |
+|-------|---------|---------------|
+| 4.5 - 5.0 | Exceptional | Ready for top-tier venue submission |
+| 4.0 - 4.4 | Strong | Minor revisions needed |
+| 3.5 - 3.9 | Good | Major revisions required |
+| 3.0 - 3.4 | Acceptable | Significant rework before submission |
+| < 3.0 | Weak | Fundamental issues to address |
+
+## Contextual Adjustments
+
+**By stage:** Proposals — relax D4, D5, D6 (no results yet); weight D1, D2, D3 more heavily. Working drafts — expect D7, D8 to be lower; focus on D1-D6. Final manuscripts — full rubric, no relaxation.
+
+**By venue tier:** Workshop/conference papers — accept 3.5+ overall. CABS 3 journals — target 4.0+. CABS 4/4* or FT 50 — target 4.5+; all dimensions should be 4+.
+
+**By paper type:** Theoretical papers — D4 may be N/A (re-weight to D1-D3). Empirical papers — full rubric applies. Review/survey papers — D4-D6 may be N/A; weight D2 at 30%.
+
+When a dimension is N/A, redistribute its weight proportionally across the remaining dimensions.
+
+## Agent Integration
+
+| Agent | Loads | Dimensions used |
+|-------|-------|----------------|
+| `referee2-reviewer` | Always | All 8 (full scorecard) |
+| `domain-reviewer` | When scoring requested | D1, D3, D5 (overlap with its domain lenses) |
+| `paper-critic` | When scoring requested | D7, D8 (overlap with writing/citation categories) |
+| `/pre-submission-report` | Always | Aggregate weighted score in summary |
+
+Agents should report per-dimension scores in a table, then the weighted aggregate, then the verdict. Use the checklist items as evidence anchors for each score.

package/skills/shared/rhetoric-principles.md

@@ -0,0 +1,54 @@
+# Rhetoric Principles for Presentations
+
+> Shared reference for `/beamer-deck`, `/quarto-deck`, and `/quarto-course`. Drawn from Scott Cunningham's "The Rhetoric of Decks" essay.
+> Full source: `resources/academics/scott-cunningham/MixtapeTools/presentations/rhetoric_of_decks.md`
+
+## The Three Laws
+
+| Law | Principle |
+|-----|-----------|
+| **Beauty Is Function** | Every element earns its presence. Decoration without function is noise. A slide with three words on a blank background can be the most beautiful. |
+| **Cognitive Load Is the Enemy** | Audience has limited working memory. Too many points = zero points retained. One idea per slide — not a guideline, a law. |
+| **The Slide Serves the Spoken Word** | Slides provide focal points, memory hooks, evidence, structural markers. If slides work without speaking, you've written a document, not a presentation. |
+
+## MB/MC Equivalence
+
+Optimal rhetoric equalises the marginal-benefit-to-marginal-cost ratio across all slides. For each slide ask: "If I added one more element, would benefit justify cognitive cost? If I removed one, would I lose more than I'd gain in clarity?" When every slide answers "I'm at the margin," you're optimised.
+
+- **Overloaded slides** (MB/MC too low): text running to footer, competing ideas, charts with too many series.
+- **Underloaded slides** (MB/MC too high): single word that could support a sentence, wasted attention.
+- **Rhythm**: vary dense and light slides deliberately.
+
+## Aristotelian Triad
+
+| Mode | Role in decks | Danger if absent |
+|------|---------------|------------------|
+| **Ethos** (credibility) | Process diagrams, acknowledged limitations, Devil's Advocate slides | Audience won't trust you |
+| **Pathos** (emotion) | Open with a recognised problem, connect data to human impact | Audience won't care |
+| **Logos** (logic) | Data viz revealing patterns, comparison tables, problem→solution flow | Audience won't follow |
+
+## Narrative Arc (Three Acts)
+
+1. **Act I — Problem (Tension):** Establish status quo, introduce disruption, make audience feel the problem.
+2. **Act II — Investigation (Development):** Show what you tried, present what you learned, build the logical case.
+3. **Act III — Resolution (Release):** Deliver insight, show implications, call to action.
+
+## Pyramid Principle
+
+Lead with the conclusion, then support it. Humans want the punchline first, then the reasoning.
+
+- **Opening slide**: Provocative question, surprising statistic, bold claim. Never "Today I'm going to talk about..."
+- **Closing slide**: Single memorable takeaway or return to opening, resolved. Never "Questions?" or "Thank you."
+
+## The Devil's Advocate
+
+Before presenting your argument, present its strongest critique. Show anticipated objections, weaknesses you acknowledge, mitigations you've developed. Format: "A skeptic would say..." → your response.
+
+## Context-Specific Guidance
+
+| Audience | Ethos/Pathos/Logos | Key adjustments |
+|----------|-------------------|-----------------|
+| **Academic seminar** | 20% / 35% / 45% | Lead with the puzzle, not the literature. Identification strategy early. One coefficient at a time. Acknowledge limitations before Q&A. |
+| **Conference talk** | 25% / 35% / 40% | Emphasise identification strategy and key results. Tight narrative — no tangents. |
+| **Teaching lecture** | 20% / 30% / 50% | Brevity < clarity. Repetition is allowed. Show reasoning, not just conclusions. Pause points for questions. |
+| **Working deck** | 30% / 10% / 60% | Document choices (why A over B?). Preserve uncertainty. Show the math. Prioritise rigor over polish. |

package/skills/shared/skill-design-patterns.md

@@ -0,0 +1,272 @@
+# Skill Design Patterns
+
+> Reference for designing new skills. Read this before writing any SKILL.md.
+> Loaded on demand by `/learn` and when manually creating skills.
+
+## Structural Patterns
+
+Choose based on what the skill does. Most skills fit one pattern; some combine two.
+
+### Workflow-Based
+
+Multi-step processes where order matters and user approval is needed between phases.
+
+```
+Phase 1: Gather → Phase 2: Process → REVIEW GATE → Phase 3: Output
+```
+
+**When to use:** Report generation, project bootstrapping, multi-pass analysis, content creation with review cycles.
+
+**Key elements:**
+- Numbered phases with explicit entry/exit criteria
+- Review gates between phases (hard stops where the agent presents work and waits)
+- Default assumptions table to reduce friction
+
+
+### Task-Based
+
+Focused input/output with clear processing rules. No phases — just do the thing well.
+
+```
+Input spec → Processing rules → Output spec → Quality checks
+```
+
+**When to use:** Code review, proofreading, validation, data transformation, file conversion.
+
+**Key elements:**
+- Explicit input format and constraints
+- Processing rules as imperative instructions
+- Output format specification
+- Verification criteria
+
+
+### Agent-Delegation
+
+Multiple subagents, each responsible for a distinct concern. Coordinator manages handoffs.
+
+```
+Coordinator → Subagent A (generate) → Subagent B (critique) → Coordinator (synthesize)
+```
+
+**When to use:** Tasks where quality benefits from separation of concerns — writing with editing, analysis with critique, multi-perspective evaluation.
+
+**Key elements:**
+- `agents/` directory or Task tool delegation with focused system prompts
+- Each subagent does one thing well
+- Coordinator synthesizes outputs
+
+
+### Reference-Based
+
+Augments the agent with domain knowledge it lacks, loaded on demand.
+
+```
+SKILL.md (routing + procedures) → references/ (domain knowledge)
+```
+
+**When to use:** Specialized domains where training data is insufficient — niche APIs, internal conventions, proprietary formats, scoring rubrics.
+
+**Key elements:**
+- SKILL.md stays concise — routing logic and procedures only
+- `references/` contains detailed specs, lookup tables, scoring rubrics
+- Agent reads references on demand, not all at once
+
+
+---
+
+## Design Elements
+
+### Review Gates
+
+Prevent runaway execution by requiring user approval at checkpoints.
+
+```markdown
+### REVIEW GATE: [Gate Name]
+
+Present the following to the user and STOP:
+- [What to show]
+- [What to show]
+
+Do NOT proceed until the user explicitly approves.
+```
+
+Place gates after planning/before execution, and after first draft/before refinement.
+
+### Anti-Pattern Lists
+
+Tell the agent what NOT to do. Agents default to safe, generic patterns unless explicitly constrained. Negative constraints are as important as positive instructions.
+
+```markdown
+## Never Do These
+
+- Never use "leverage" — use "use" instead
+- Never produce bullet points when a table would be clearer
+- Never assume verbose output — default to concise
+```
+
+### Default Assumptions Table
+
+Reduce friction by pre-answering common questions. Only ask the user what can't be reasonably defaulted.
+
+```markdown
+## Defaults
+
+| Setting | Default | Override |
+|---------|---------|---------|
+| Output format | Markdown | User specifies otherwise |
+| Verbosity | Concise | User says "detailed" |
+| Location | Project root | User provides path |
+```
+
+### Drift Prevention
+
+Skills that reference external state (database schemas, file counts, theme lists, status options) go stale silently. Use this 3-part pattern when a skill has hardcoded values derived from mutable sources.
+
+**Part 1: Runtime detection (Phase 0)**
+
+Add a Phase 0 at the start of the skill that checks hardcoded values against reality before proceeding:
+
+```markdown
+## Phase 0: Drift Detection
+
+Before starting, verify skill references:
+1. Count actual {items} — compare against ~N in this skill
+2. List actual {categories} — compare against the N listed here
+3. Fetch {schema/config} — verify properties still match
+
+If drift detected:
+- Warn in output header: "⚠ Drift: {what} was {expected}, actually {found}"
+- Use actual values for this run (self-heal)
+- Log to references/drift-checks.md
+```
+
+**Part 2: Drift reference file**
+
+Create `references/drift-checks.md` listing every drift-prone value:
+
+```markdown
+| Value | Location | Source of Truth | Trigger |
+|-------|----------|-----------------|---------|
+| Topic count (~67) | SKILL.md Phase 1 | ls topics/**/*.md | /scaffold-atlas-topics |
+| Theme list (9) | SKILL.md, sa-prompts.md, build_report.py | ls Projects/ | New theme dir |
+```
+
+Include a Drift Log table where Phase 0 appends detected drift with timestamps.
+
+**Part 3: Trigger notes in related skills**
+
+Add cross-references in skills that commonly cause drift:
+
+```markdown
+| `/atlas-review` | **Drift trigger:** new topics change count — see drift-checks.md |
+```
+
+This ensures the person (or agent) running the triggering skill is aware that downstream skills may need updating.
+
+**When to use:** Any skill with hardcoded counts, database IDs, schema property names, status option lists, file paths derived from external systems, or theme/category lists that grow over time.
+
+**When to skip:** Skills that derive all values at runtime (no hardcoded references to external state).
+
+**Example:** `/atlas-review` — topic count, theme list, vault schemas, stage mappings, rules count all drift. Phase 0 detects and self-heals; `references/drift-checks.md` tracks 8 drift-prone values.
+
+### Progressive Disclosure
+
+Control what goes where based on how often the agent needs it:
+
+| Location | Loaded | Use for |
+|----------|--------|---------|
+| `name` + `description` | Always in context | Trigger matching — when to activate |
+| SKILL.md body | When skill triggers | Core procedures, workflow, constraints |
+| `references/` | On demand via Read | Detailed specs, large examples, lookup tables |
+| `scripts/` | On demand via Bash | Deterministic operations (validation, formatting) |
+
+**Rule of thumb:** If the agent needs it every time → SKILL.md body. If it needs it sometimes → `references/`. If it should execute it → `scripts/`.
+
+---
+
+## Writing Guidelines
+
+### For the Description (Frontmatter)
+
+The `description` determines when the skill activates. It's always in context. **Write in third person** — the description is injected into the system prompt, and inconsistent point-of-view causes discovery problems.
+
+**Good:**
+- `"Analyze datasets using statistical methods. Handles EDA, hypothesis testing, and causal inference. Use when asked to analyze CSV/Excel data or run A/B test analysis."`
+- `"Academic proofreading for LaTeX papers. Grammar, notation consistency, citation format, tone. Report-only — never edits source files."`
+
+**Bad:**
+- `"A helpful skill"` — too vague, triggers on everything
+- `"I can help you process files"` — wrong point-of-view (first person)
+- `"Skill for doing things with files"` — will trigger on every file operation
+
+**Tips:**
+- Lead with the primary capability
+- Include concrete task types as trigger phrases
+- End with "Use when..." to define activation conditions
+- State what it does NOT do if there's a common confusion
+- Max 1024 characters; name max 64 characters (lowercase, hyphens, numbers only)
+
+### For the Body (System Prompt)
+
+- **Write for an AI agent, not a human.** Procedural knowledge the agent cannot infer.
+- **Imperative form.** "Parse the input" not "You should parse the input."
+- **Be specific about what NOT to do.** Anti-pattern lists are highly effective.
+- **Include concrete examples.** Input/output pairs and good/bad snippets beat abstract rules.
+- **Keep SKILL.md under 500 lines** (Anthropic official threshold). Move detailed specs and large examples to `references/`. Aim for under 300 lines when possible.
+- **Every instruction must be actionable.** If the agent cannot act on a sentence, delete it.
+- **Use tables for structured data.** Defaults, field specs, command references — tables are faster to parse than prose.
+- **One section, one concern.** Don't mix workflow steps with quality criteria.
+
+### For allowed_tools
+
+Follow principle of least privilege:
+
+| Skill type | Tools |
+|-----------|-------|
+| Report-only | `Read`, `Glob`, `Grep` |
+| File-creating | + `Write`, `Edit` |
+| Shell-needing | + specific `Bash(command*)` patterns |
+| Interactive | + `AskUserQuestion` |
+| Delegating | + `Task` |
+
+---
+
+## Quality Checklist
+
+Before finalising any skill, verify:
+
+| Check | Question |
+|-------|----------|
+| Trigger clarity | Would Claude know when to invoke this from the description alone? |
+| Pattern fit | Does the structure match one of the 4 patterns above? |
+| No duplication | Does this overlap with an existing skill? |
+| Anti-patterns | Does it say what NOT to do, not just what to do? |
+| Examples present | Are there concrete before/after or good/bad examples? |
+| Minimum tools | Only the tools actually needed are in `allowed_tools`? |
+| No secrets | No API keys, tokens, or passwords? |
+| References extracted | Is detailed reference material in `references/`, not inline? |
+| Description specificity | Would the description distinguish this from similar skills? |
+| Tested | Has the procedure been tested, not just theorised? |
+| Refs one-level deep | All reference files link directly from SKILL.md (no nested refs)? |
+| Third-person description | Description uses "Processes..." not "I can..." or "You can..."? |
+
+---
+
+## Evaluation-Driven Development
+
+Per [Anthropic's official best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices):
+
+1. **Identify gaps:** Run Claude on representative tasks without the skill. Document specific failures.
+2. **Create evaluations:** Build 3+ scenarios that test these gaps.
+3. **Establish baseline:** Measure Claude's performance without the skill.
+4. **Write minimal instructions:** Just enough to address the gaps and pass evaluations.
+5. **Iterate:** Execute evaluations, compare against baseline, refine.
+
+### Claude A / Claude B Pattern
+
+- **Claude A** (the expert): helps design and refine the skill
+- **Claude B** (the user): tests the skill in real tasks with fresh context
+- Observe Claude B's behavior, bring insights back to Claude A
+- Repeat: observe → refine → test
+
+This is similar to the existing `/skill-creator` workflow but emphasises real-task testing over synthetic evaluation.