@brainpilot/skills 0.0.6

package/skills/01_Meta-Skills/paper-to-skill/references/extraction-guide.md

@@ -0,0 +1,286 @@
+# Extraction Guide: Paper-Type-Specific Strategies
+
+This guide defines how to extract research paradigms and methodological techniques from different types of cognitive science and neuroscience papers. Each paper type has distinct sections where extractable knowledge concentrates and distinct priorities for what to capture.
+
+---
+
+## 1. Experimental Papers
+
+**Identification**: Contains original experiments with human (or animal) participants, reports behavioral and/or neural data.
+
+**Primary extraction targets** (in priority order):
+
+### 1.1 Paradigm Design Parameters
+
+- **Where to find**: Methods → Experimental Design / Task / Procedure
+- **Extract**:
+ - Paradigm name and type (e.g., "modified Sternberg paradigm", "rapid serial visual presentation")
+ - Full trial structure with timing diagram:
+ - Fixation cross duration (ms)
+ - Stimulus onset and duration (ms)
+ - Inter-stimulus interval / SOA (ms)
+ - Response window onset and duration (ms)
+ - Inter-trial interval (ms), including jitter range if applicable
+ - Feedback duration (ms), if present
+ - Number of conditions and their operational definitions
+ - Number of trials per condition and total trial count
+ - Number of blocks and trials per block
+ - Break/rest interval duration and frequency
+ - Counterbalancing scheme:
+ - Condition-to-response mapping rotation
+ - Stimulus list assignment (Latin square design details)
+ - Block order randomization constraints
+ - Practice trials: count, whether feedback was provided, exclusion criteria
+ - Catch trial percentage and purpose (if applicable)
+
+### 1.2 Data Acquisition Parameters
+
+- **Where to find**: Methods → EEG/fMRI/MEG Recording / Apparatus / Data Acquisition
+- **Extract by modality**:
+
+ **EEG**:
+ - Amplifier system (manufacturer, model)
+ - Electrode count, montage standard (10-20, 10-10, custom)
+ - Online reference and ground electrodes
+ - Sampling rate (Hz)
+ - Online filter settings (high-pass, low-pass, notch)
+ - Impedance threshold (kOhm)
+ - Additional channels (EOG, EMG) and their placement
+
+ **fMRI**:
+ - Scanner field strength (T) and manufacturer
+ - Coil type (e.g., 32-channel head coil)
+ - Functional scan parameters: TR (ms), TE (ms), flip angle (degrees), voxel size (mm), matrix size, slice count, slice order (ascending/interleaved), multi-band acceleration factor
+ - Structural scan parameters: sequence type (MPRAGE, etc.), resolution, TR, TE, TI
+ - Number of functional volumes and dummy scans discarded
+ - Field map acquisition (if used)
+
+ **Eye-tracking**:
+ - System model and manufacturer
+ - Sampling rate (Hz)
+ - Tracking mode (remote vs. chin rest)
+ - Calibration type (5-point, 9-point, 13-point) and acceptance criteria
+ - Fixation definition: dispersion threshold, minimum duration
+ - Saccade detection: velocity threshold, acceleration threshold
+
+ **Behavioral**:
+ - Response device (keyboard, button box, joystick, touchscreen)
+ - Response mapping (which keys/buttons for which responses)
+ - Timeout/deadline (ms)
+ - Presentation software and version
+
+### 1.3 Data Processing Pipeline
+
+- **Where to find**: Methods → Data Analysis / EEG Processing / Preprocessing / fMRI Analysis
+- **Extract as an ordered sequence**:
+ 1. Software and version (e.g., "MNE-Python 1.3.0", "SPM12", "EEGLAB 2022.1")
+ 2. Each preprocessing step in order, with parameters:
+ - Filtering: type (FIR/IIR/Butterworth), cutoffs (Hz), order or transition bandwidth, zero-phase or causal
+ - Re-referencing: scheme (average, linked mastoids, Cz, REST)
+ - Downsampling: target rate (Hz)
+ - Epoching: event-locked to what, time window (ms), baseline window (ms)
+ - Artifact detection: method and thresholds (peak-to-peak amplitude uV, flat channel detection, EOG threshold)
+ - ICA: algorithm (Infomax, FastICA, AMICA), number of components, component rejection criteria
+ - Channel interpolation: method (spherical spline), criteria for bad channel identification
+ - Trial rejection rate and participant exclusion threshold
+ 3. For fMRI: slice timing correction, motion correction, normalization template and parameters, smoothing kernel FWHM (mm)
+
+### 1.4 Analysis Methods
+
+- **Where to find**: Methods → Statistical Analysis / Data Analysis; Results
+- **Extract**:
+ - Statistical tests with full specification (e.g., "2 x 3 repeated-measures ANOVA with factors Condition (congruent, incongruent) and Region (frontal, central, parietal)")
+ - Mixed-effects model specification: fixed effects, random effects structure, optimizer
+ - Multiple comparison correction: method (Bonferroni, FDR, cluster-based permutation), parameters (alpha level, cluster-forming threshold, number of permutations)
+ - Time window / ROI selection: how chosen (a priori, data-driven, literature-based), exact values
+ - Effect size measures reported (Cohen's d, partial eta-squared, Bayes factor)
+ - Post-hoc test method
+ - Software used for statistics (R package, MATLAB function, Python library)
+
+### 1.5 Stimulus Materials
+
+- **Where to find**: Methods → Materials / Stimuli; sometimes Supplementary Materials
+- **Extract**:
+ - Material type and total count
+ - Per-condition counts
+ - Controlled lexical/visual/auditory variables and their matching criteria
+ - Norming database used (with citation)
+ - Specific ranges or means for controlled variables (e.g., "word frequency: M = 4.2, range 2.1-6.8 per million, SUBTLEX-US")
+ - Presentation parameters: visual angle, font/size, luminance, duration, position on screen
+ - Filler/catch trial composition
+
+---
+
+## 2. Methods Papers
+
+**Identification**: Introduces, validates, or benchmarks a new analysis technique, software tool, or processing pipeline. May include simulated data or re-analysis of existing datasets.
+
+**Primary extraction targets** (in priority order):
+
+### 2.1 Complete Analysis Pipeline
+
+- **Where to find**: Methods → Algorithm / Pipeline / Procedure; often the entire paper IS the method
+- **Extract the full pipeline as a numbered sequence**:
+ 1. Input data format and requirements
+ 2. Each processing step with:
+ - Algorithm name and mathematical formulation (if provided)
+ - Default parameter values and their justification
+ - Parameter sensitivity analysis results (which parameters matter most)
+ - Computational requirements (runtime, memory)
+ 3. Output format and interpretation guidelines
+
+### 2.2 Parameter Selection Rationale
+
+- **Where to find**: Methods, Results (parameter sweeps), Discussion
+- **Extract**:
+ - Recommended default values for each parameter
+ - How defaults were determined (simulation, empirical optimization, theoretical derivation)
+ - Parameter ranges tested and their effects on performance
+ - Guidelines for when to adjust defaults (data characteristics that warrant different settings)
+ - Known failure modes and parameter settings that cause them
+
+### 2.3 Validation Methods
+
+- **Where to find**: Results → Validation / Benchmarking / Comparison
+- **Extract**:
+ - Ground truth definition (simulated data specs, known-result datasets)
+ - Performance metrics used (sensitivity, specificity, AUC, RMSE)
+ - Comparison against existing methods (which methods, what outcomes)
+ - Dataset characteristics where the method excels or fails
+ - Recommended validation procedure for new users
+
+### 2.4 Implementation Details
+
+- **Where to find**: Methods, Supplementary Materials, code repositories
+- **Extract**:
+ - Programming language and dependencies (with versions)
+ - Input/output specifications
+ - Code repository URL (if provided)
+ - Key function names or API entry points
+ - Known limitations and edge cases
+
+---
+
+## 3. Computational Modeling Papers
+
+**Identification**: Constructs, fits, or compares formal mathematical/computational models of cognitive processes. May include behavioral or neural data for model fitting.
+
+**Primary extraction targets** (in priority order):
+
+### 3.1 Model Equations and Architecture
+
+- **Where to find**: Methods → Model / Computational Framework; sometimes Theory section
+- **Extract**:
+ - Model name and class (e.g., "drift-diffusion model", "Bayesian ideal observer", "recurrent neural network")
+ - Complete mathematical specification:
+ - All equations with variable definitions
+ - Relationship between equations (what feeds into what)
+ - Boundary/initial conditions
+ - Free parameters vs. fixed parameters (list each with role)
+ - Model variants tested (if multiple versions compared)
+
+### 3.2 Parameter Constraints and Priors
+
+- **Where to find**: Methods → Model Fitting / Parameter Estimation
+- **Extract**:
+ - For each free parameter:
+ - Name and cognitive interpretation
+ - Constraint bounds (lower, upper)
+ - Prior distribution (if Bayesian): family, hyperparameters, justification
+ - Starting values for optimization (if frequentist)
+ - Parameter recovery analysis results (if reported)
+ - Identifiability analysis (which parameters can be independently estimated)
+
+### 3.3 Fitting Methods
+
+- **Where to find**: Methods → Model Fitting / Parameter Estimation / Optimization
+- **Extract**:
+ - Fitting objective: maximum likelihood, least squares, Bayesian posterior
+ - Optimization algorithm: name (Nelder-Mead, differential evolution, MCMC), implementation (software, package)
+ - For MCMC: number of chains, samples per chain, burn-in, thinning, convergence diagnostic (R-hat threshold)
+ - For MLE: number of starting points, convergence criteria
+ - Data summary statistics used for fitting (if not fitting raw trial data)
+ - Cross-validation procedure (if used)
+
+### 3.4 Model Comparison Strategy
+
+- **Where to find**: Results → Model Comparison / Model Selection
+- **Extract**:
+ - Comparison metric: AIC, BIC, WAIC, DIC, Bayes factor, cross-validation log-likelihood
+ - How group-level comparison was performed (summed individual fits, hierarchical, fixed-effects)
+ - Confusion matrix / model recovery analysis (if reported)
+ - Winning model and by what margin
+ - Qualitative fit assessment: which data patterns does each model capture or miss
+
+### 3.5 Simulation Procedures
+
+- **Where to find**: Methods → Simulation / Predictions; Results
+- **Extract**:
+ - Simulation parameter settings (which parameter values, how chosen)
+ - Number of simulated datasets / participants / trials
+ - Random seed handling (if reported)
+ - What predictions were generated and how they were compared to data
+
+---
+
+## 4. Review and Theoretical Papers
+
+**Identification**: Synthesizes existing literature, proposes theoretical frameworks, or provides meta-analyses. Does not contain new experimental data (meta-analyses may contain re-analyzed data).
+
+**Primary extraction targets** (in priority order):
+
+### 4.1 Theory-to-Experiment Mapping
+
+- **Where to find**: Throughout; often in dedicated "Predictions" or "Implications" sections
+- **Extract**:
+ - Theoretical constructs and their proposed operationalizations
+ - Predicted dissociations between conditions (what pattern would support vs. refute the theory)
+ - Suggested experimental paradigms for testing predictions
+ - Recommended dependent variables and expected effect directions
+
+### 4.2 Recommended Paradigm Combinations
+
+- **Where to find**: Discussion, "Future Directions", tables comparing studies
+- **Extract**:
+ - Which paradigms are recommended for measuring specific constructs
+ - Multi-method convergence recommendations (e.g., "combine ERP and eye-tracking for this question")
+ - Paradigm comparison tables: which paradigm is best for which research question
+ - Known confounds in specific paradigms and suggested controls
+
+### 4.3 Meta-Analytic Parameters (if meta-analysis)
+
+- **Where to find**: Methods → Literature Search / Inclusion Criteria; Results
+- **Extract**:
+ - Inclusion/exclusion criteria for studies
+ - Effect size calculation method
+ - Overall effect size with confidence interval
+ - Moderator analysis results (which study features influence effect size)
+ - Publication bias assessment method and result
+ - Recommended sample size based on meta-analytic effect size
+
+### 4.4 Methodological Recommendations
+
+- **Where to find**: Discussion, "Best Practices" sections, "Recommendations", tables comparing approaches
+- **Extract**:
+ - Specific parameter recommendations with justification and evidence strength (e.g., "Use high-pass filter cutoff of 0.1 Hz, not 0.01 Hz, because..." with citation)
+ - Recommended analysis pipelines as step-by-step sequences with default parameter values
+ - Decision trees or flowcharts for method selection (e.g., "if data has >20% artifact rate, use ICA; if <10%, use threshold rejection")
+ - Meta-analytic effect sizes with confidence intervals, and moderator variables that influence them
+ - Sample size recommendations computed from the meta-analytic effect sizes and desired power
+ - Common methodological pitfalls identified across studies, with concrete examples of how they manifest and how to avoid them
+ - Reporting standards recommended by the review (e.g., "always report filter order and transition bandwidth")
+ - Parameter ranges where community consensus exists vs. where it does not
+
+---
+
+## Cross-Cutting Extraction Rules
+
+These rules apply regardless of paper type:
+
+1. **Preserve exact numbers** — Never round. If the paper says "513 ms", write "513 ms", not "~500 ms".
+2. **Track the source location** — Note section, page, table, or figure number for each extracted value.
+3. **Flag missing information** — If a standard parameter is not reported, explicitly note its absence.
+4. **Capture rationale** — When authors explain WHY they chose a parameter value, capture that justification.
+5. **Note deviations** — When authors explicitly deviate from convention, capture both what they did and why.
+6. **Extract from figures** — Parameters sometimes appear only in figures or figure captions. Read these carefully.
+7. **Check supplementary materials** — Methods papers and experimental papers increasingly put critical details in supplements.

package/skills/01_Meta-Skills/paper-to-skill/references/skill-template.md

@@ -0,0 +1,250 @@
+# Skill Template for Generated Skills
+
+This template defines the standard structure for skills generated by the Paper-to-Skill Extractor. All generated skills must conform to this template to satisfy the project conventions defined in [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+
+---
+
+## Template Structure
+
+````markdown
+---
+name: "<Human-Readable-Skill-Name>"
+description: "<One-sentence summary of the domain knowledge encoded>"
+domain: "<subdomain>"
+version: "1.0.0"
+papers:
+ - "<Author et al., Year>"
+---
+
+# <Skill Name>
+
+<One paragraph overview: what method/paradigm this skill encodes, when to use it, and what domain it applies to.>
+
+**Source**: <Full APA-style citation of the source paper>
+
+---
+
+## When to Use This Skill
+
+<Bullet list of concrete scenarios where this skill applies. Each bullet should describe a research situation, not a generic statement.>
+
+- When designing a study that investigates <specific cognitive process>
+- When processing <specific data type> from <specific recording setup>
+- When analyzing <specific dependent variable> in <specific experimental context>
+
+---
+
+## <Section Title Matching Extracted Content>
+
+<This section contains the core domain knowledge. The section title should match the content type:>
+
+- For paradigm designs: "Paradigm Design" or "Experimental Design"
+- For data acquisition: "Recording Setup" or "Acquisition Parameters"
+- For preprocessing: "Preprocessing Pipeline"
+- For analysis methods: "Analysis Procedure"
+- For stimulus specs: "Stimulus Specifications"
+
+### <Subsection for Specific Parameters>
+
+<Present parameters in structured format. Every numerical value must include a citation.>
+
+| Parameter | Value | Source Location | Citation |
+|---|---|---|---|
+| <Parameter name> | <Exact value with unit> | <Section X.Y / Table N / Figure N> | (<Author, Year>, p. X / Table Y) |
+| <Parameter name> | <Exact value with unit> | <Section X.Y / Table N / Figure N> | (<Author, Year>, p. X / Table Y) |
+
+<Or use bullet list format for sequential procedures:>
+
+1. **<Step name>**: <Description with exact parameters> (<Author, Year>)
+2. **<Step name>**: <Description with exact parameters> (<Author, Year>)
+
+---
+
+## Decision Points
+
+<Document any decisions a researcher must make when applying this skill, and provide guidance from the source paper.>
+
+- **<Decision>**: <Options and recommendation with rationale from the paper>
+- **<Decision>**: <Options and recommendation with rationale from the paper>
+
+---
+
+## Common Pitfalls
+
+<List methodological pitfalls mentioned in or implied by the source paper.>
+
+- <Pitfall description and how to avoid it>
+- <Pitfall description and how to avoid it>
+
+---
+
+## Validation Checklist
+
+Before using this skill in a study, verify:
+
+- [ ] <Check relevant to this specific method>
+- [ ] <Check relevant to this specific method>
+- [ ] All numerical parameters match your recording setup / population / research question
+- [ ] Deviations from the source parameters are justified and documented
+
+---
+
+## Missing Information
+
+<List standard parameters for this method type that the source paper does not report. This helps users know what they must determine independently.>
+
+- **<Parameter name>**: Not reported. Standard value from <reference/field convention> is <value>.
+- **<Parameter name>**: Not reported. Must be determined empirically for your setup.
+
+---
+
+## Deviations from Convention
+
+<List methodological choices that deviate from field conventions, with the authors' stated rationale.>
+
+- **<Choice>**: Authors used <X> instead of conventional <Y> because <reason> (<Author, Year>, p. N).
+
+---
+
+## References
+
+- <Full APA citation for the source paper>
+- <Any additional references cited in the skill>
+````
+
+---
+
+## Template Usage Rules
+
+### Mandatory Elements
+
+Every generated skill MUST include:
+
+1. **YAML frontmatter** with `name`, `description`, and `papers` fields
+2. **Source citation** — full reference to the paper the skill was extracted from
+3. **"When to Use" section** — at least 2 concrete scenarios
+4. **Core content section** — with all parameters cited and source locations tracked
+5. **Missing Information section** — listing any standard parameters not reported (may be empty with a note)
+6. **Deviations from Convention section** — listing non-standard choices (may be empty with a note)
+7. **References section** — full citations for all papers referenced
+
+### Optional Elements
+
+Include these when the source paper provides sufficient information:
+
+- **Decision Points** — when the method involves researcher judgment calls
+- **Common Pitfalls** — when the paper discusses what can go wrong
+- **Validation Checklist** — when there are preconditions for applying the method
+
+### Formatting Rules
+
+1. **Parameter tables**: Use for sets of related parameters (e.g., all EEG recording settings). Include columns for Parameter, Value, Source Location, and Citation.
+2. **Numbered lists**: Use for sequential procedures (pipelines, step-by-step protocols). Preserve the original order.
+3. **Bullet lists**: Use for non-sequential items (decision points, pitfalls, recommendations).
+4. **Bold text**: Use for parameter values inline — e.g., "Apply a bandpass filter of **0.1 - 30 Hz**".
+5. **Code blocks**: Use sparingly. Only include code when the paper provides specific function calls or pseudocode that constitutes domain knowledge (not generic programming).
+
+### Citation Format Within Generated Skills
+
+Follow the citation format defined in [CONTRIBUTING.md](../../../CONTRIBUTING.md):
+
+```markdown
+- Reject epochs with peak-to-peak amplitude > **100 uV** (Luck, 2014)
+- Apply bandpass filter: **0.1 - 30 Hz** (Widmann et al., 2015)
+```
+
+For parameters from the source paper itself:
+
+```markdown
+- Trial duration: **1500 ms** (Smith et al., 2023, Table 1)
+- ISI jittered: **400 - 600 ms** (Smith et al., 2023)
+```
+
+### Line Count Management
+
+- The SKILL.md must stay under **500 lines**
+- If the extracted content exceeds this limit, move detailed parameter tables or extended pipeline descriptions into `references/` files
+- The SKILL.md should always contain enough information to be useful on its own; `references/` files provide supplementary depth
+
+### Overflow File Conventions
+
+When content must be moved to `references/`:
+
+| Content Type | File Name | Format |
+|---|---|---|
+| Full parameter table | `parameter-table.yaml` | YAML |
+| Extended pipeline steps | `pipeline-steps.md` | Markdown |
+| Stimulus specifications | `stimulus-specs.yaml` | YAML |
+| Statistical model details | `model-specification.md` | Markdown |
+| Validation benchmarks | `validation-data.csv` | CSV |
+
+Reference these files explicitly in the SKILL.md:
+
+```markdown
+> See `references/parameter-table.yaml` for the complete recording parameter set.
+```
+
+---
+
+## Example: Generated Skill from an ERP Study
+
+Below is a abbreviated example showing how a real extraction would look:
+
+````markdown
+---
+name: "MMN Oddball Paradigm — Auditory Duration Deviant"
+description: "Complete paradigm design and ERP analysis parameters for auditory mismatch negativity using duration deviants"
+domain: "erp-paradigm"
+version: "1.0.0"
+papers:
+ - "Naatanen et al., 2007"
+---
+
+# MMN Oddball Paradigm — Auditory Duration Deviant
+
+This skill encodes the experimental paradigm and ERP analysis pipeline for eliciting the auditory mismatch negativity (MMN) component using a duration-deviant oddball task. The MMN is a pre-attentive index of auditory change detection, peaking at 100-250 ms post-stimulus onset at fronto-central electrodes.
+
+**Source**: Naatanen, R., Paavilainen, P., Rinne, T., & Alho, K. (2007). The mismatch negativity (MMN) in basic research of central auditory processing: A review. *Clinical Neurophysiology*, 118(12), 2544-2590.
+
+---
+
+## When to Use This Skill
+
+- When designing an auditory MMN study using duration deviants
+- When setting ERP preprocessing parameters for auditory oddball data
+- When defining analysis time windows and electrode sites for MMN quantification
+
+---
+
+## Paradigm Design
+
+### Trial Structure
+
+| Parameter | Value | Source Location | Citation |
+|---|---|---|---|
+| Standard tone duration | **75 ms** | | (Naatanen et al., 2007) |
+| Deviant tone duration | **25 ms** | | (Naatanen et al., 2007) |
+| Tone frequency | **1000 Hz** (sinusoidal) | | (Naatanen et al., 2007) |
+| Rise/fall time | **5 ms** | | (Naatanen et al., 2007) |
+| SOA | **500 ms** | | (Naatanen et al., 2007) |
+| Deviant probability | **10-20%** | | (Naatanen et al., 2007) |
+| Minimum standards between deviants | **2** | | (Naatanen et al., 2007) |
+
+## Analysis Parameters
+
+### MMN Quantification
+
+| Parameter | Value | Source Location | Citation |
+|---|---|---|---|
+| Time window | **100-250 ms** post-stimulus | | (Naatanen et al., 2007) |
+| Electrode sites | **Fz, FCz, Cz** | | (Naatanen et al., 2007) |
+| Reference | Average or nose reference | | (Naatanen et al., 2007) |
+| Measurement | Mean amplitude in window | | (Naatanen et al., 2007) |
+| Difference wave | Deviant ERP minus Standard ERP | | (Naatanen et al., 2007) |
+
+---
+
+## References
+
+- Naatanen, R., Paavilainen, P., Rinne, T., & Alho, K. (2007). The mismatch negativity (MMN) in basic research of central auditory processing: A review. *Clinical Neurophysiology*, 118(12), 2544-2590.
+````