section-mapper_skill

Overview

This skill maps papers from the core set to each outline subsection and writes outline/mapping.tsv with coverage tracking. It produces a human-readable mapping (paper → subsection → short semantic why) and a diagnostics report to surface weak or overused coverage before evidence writing.

How this skill works

The tool reads outline/outline.yml and papers/core_set.csv, then assigns a target number of supporting papers to each subsection using heuristics for representativeness, complementarity, and reuse limits. It writes outline/mapping.tsv and a diagnostics file (outline/mapping_report.md). It backs up existing mappings unless an explicit freeze marker is present and flags subsections with weak signal or excessive reuse.

When to use it

• You have outline/outline.yml and papers/core_set.csv and need subsection-level evidence coverage.
• You want to detect weak-signal subsections before starting evidence-first writing.
• You need an explainable paper→section mapping for reviewers or collaborators.
• You plan to enforce diversity so a few papers don't answer every subsection.
• You are preparing to run evidence collection or writing stages and need mapping locked.

Best practices

• Aim for ≥3 mapped papers per subsection; use higher per-subsection targets for comprehensive reviews.
• Include a one-line semantic ‘why’ for each mapping (mechanism, evaluation, or safety rationale).
• Penalize repeated reuse of the same paper across unrelated subsections to preserve diversity.
• If many subsections are weak, either expand the core set or merge/broaden subsections.
• Create outline/mapping.refined.ok to freeze mappings after manual refinement.

Example use cases

• Mapping a core literature set to a proposed paper outline to find gaps before drafting evidence.
• Generating a diagnostics report to show reviewers which subsections need more retrieval or scope changes.
• Applying diversity penalties to avoid canonical papers appearing in every subsection.
• Quickly producing a mapping.tsv for downstream evidence collection scripts with a set per-subsection target.
• Backing up prior mappings automatically when iterating on mapping rationales.