@pikaa-ai/pikaa 0.3.23 → 0.3.24

package/skills/scientific-writing/SKILL.md

@@ -1,356 +0,0 @@
----
-name: scientific-writing
-description: Draft, revise, and audit scientific manuscripts or reports with explicit evidence provenance, reporting-guideline coverage, authorship accountability, confidentiality controls, and local consistency checks. Use for manuscript sections, references, declarations, tables, figures, or submission preparation when scientific accuracy and traceability matter.
-license: MIT
-compatibility: Requires Python 3.11+ only for optional dependency-free local CLIs; core guidance is platform-neutral. Bundled tools are offline and require no API keys.
-metadata:
-  version: "2.0"
-  skill-author: K-Dense Inc.
----
-
-# Scientific Writing
-
-## Purpose
-
-Produce clear scientific prose without inventing evidence or concealing uncertainty.
-Keep drafting, evidence verification, and submission approval as separate stages.
-
-The accountable human authors control scientific decisions and final approval. AI is
-not an author, and generated fluency is never evidence [SW-S01, SW-S03].
-
-## Non-negotiable safety rules
-
-### Confidentiality
-
-Do not send unpublished manuscripts, peer-review or editorial material, sensitive or
-restricted data, PHI or other personal data, proprietary content, or source documents
-to an external service without:
-
-1. explicit authorization from a person or body empowered to grant it; and
-2. a documented review of journal, institutional, funder, consent, ethics, contractual,
-   legal, and data-use policy.
-
-When authorization or policy is unclear, keep processing local and use only the minimum
-metadata needed. De-identification requires expert review; removing obvious names is
-not sufficient. See `references/authorship_ai_confidentiality.md`.
-
-### No fabrication
-
-Never invent or complete:
-
-- citations, references, DOI, PMID, PMCID, ISBN, URLs, or quotations;
-- results, data values, denominators, sample sizes, units, effect estimates,
-  uncertainty, statistical tests, or significance claims;
-- methods, materials, protocol details, software versions, analysis choices, or
-  deviations;
-- registrations, approvals, consent, ethics statements, participant details, or dates;
-- authors, author order, CRediT roles, acknowledgments, or permissions;
-- funding, sponsor roles, conflicts, data or code availability, or AI disclosures.
-
-Use an explicit missing, unverified, or not-applicable state. Do not substitute plausible
-boilerplate.
-
-### Evidence binding
-
-Every factual or numeric manuscript claim must map to verified evidence IDs. A human
-verifier must open the source, confirm the proposition and locator, verify bibliographic
-metadata, and record who verified it and when.
-
-Search snippets, generated summaries, memory, and another work's bibliography may aid
-discovery but do not verify a claim. See `references/evidence_workflow.md`.
-
-### Scientific fidelity
-
-- Preserve uncertainty and alternative explanations.
-- Distinguish confirmatory, exploratory, descriptive, and post hoc work.
-- Keep methods and results consistent.
-- Reconcile units, denominators, sample sizes, populations, time points, and labels.
-- Report negative, null, adverse, unexpected, failed, and inconclusive findings when
-  they belong to the study record.
-- State concrete limitations and bound generalizability.
-- Do not convert association into causation or non-significance into equivalence.
-
-## Intake
-
-Before drafting, obtain or mark unresolved:
-
-- document type, study design, stage, audience, and target venue;
-- current author instructions and policy access date;
-- protocol, registration, analysis plan, amendments, and reporting guideline;
-- manuscript or section scope;
-- verified source manifest and claim registry;
-- methods, results, tables, figures, and supplements;
-- authorship, CRediT, declarations, and approval records;
-- confidentiality classification and authorized processing boundary;
-- data, code, materials, and repository constraints.
-
-Do not ask for restricted source material if metadata or a local user-run audit is
-sufficient.
-
-## Workflow
-
-### 1. Establish the local workspace
-
-For a new draft, optionally generate fail-closed Markdown, JSON, and CSV scaffolds:
-
-```bash
-python3 scripts/scaffold_manuscript.py \
-  --output-dir ./draft-workspace \
-  --document-id local-draft \
-  --study-design randomized_trial \
-  --guideline consort-2025
-```
-
-The generator never overwrites files. Its output is explicitly not submission-ready and
-contains placeholders that the linter rejects.
-
-### 2. Select reporting guidance
-
-Choose by actual design and article type, then open the current official statement,
-checklist, explanation document, extensions, and target-journal instructions.
-
-```bash
-python3 scripts/select_reporting_guidelines.py select \
-  --study-design randomized_trial
-```
-
-Current major routes researched on 2026-07-24 include CONSORT 2025, SPIRIT 2025,
-PRISMA 2020, STROBE, STARD and STARD-AI, TRIPOD+AI, CARE, ARRIVE 2.0, SQUIRE 2.0,
-and CHEERS 2022 [SW-S06–SW-S18].
-
-The selector is non-scoring. It does not certify quality, compliance, completeness, or
-acceptance. See `references/reporting_guidelines.md`.
-
-### 3. Build the evidence record
-
-Assign:
-
-- `E` IDs to sources in `source_manifest.json`;
-- `C` IDs to claims in `claims.csv`;
-- `N`, `M`, `O`, and `R` IDs to numeric facts, methods, outcomes, and results in
-  `consistency_manifest.json`.
-
-Store a hash of claim text in CSV rather than raw claim text. During drafting, append:
-
-```text
-[claim:C001] [evidence:E001,E002]
-```
-
-Do not mark a source verified until an accountable human has opened it and confirmed
-the exact support.
-
-### 4. Create an evidence outline
-
-Outline only from recorded evidence:
-
-- objective or question;
-- section purpose;
-- claim IDs and evidence IDs;
-- methods and result IDs;
-- analysis intent and uncertainty;
-- unresolved conflicts or missing information;
-- applicable reporting topics.
-
-Keep unsupported content in an unresolved-issues list, not manuscript prose.
-
-### 5. Draft without adding facts
-
-Transform the verified outline into venue-appropriate prose. Preserve all IDs during
-drafting.
-
-- Match title and abstract to the completed main text.
-- Describe methods as performed.
-- Present results in the declared order and analysis population.
-- Separate result from interpretation unless the venue combines them.
-- Compare with prior evidence only after verifying it.
-- Keep conclusions within the observed design, population, and uncertainty.
-
-Use IMRAD only when appropriate. Structured abstracts, lists, combined sections, and
-alternative structures depend on study design and venue. See
-`references/imrad_structure.md` and `references/writing_principles.md`.
-
-### 6. Reconcile methods and results
-
-Record repeated numeric facts and method-result mappings, then run:
-
-```bash
-python3 scripts/check_consistency.py consistency_manifest.json
-```
-
-Resolve every mismatch manually. A changed value may be a legitimate analysis-set
-difference, but that difference must be named rather than silently normalized.
-
-### 7. Verify citations and claims
-
-```bash
-python3 scripts/validate_manifest.py source_manifest.json \
-  --kind source --require-verified
-python3 scripts/audit_claims.py manuscript.md claims.csv source_manifest.json
-python3 scripts/check_references.py source_manifest.json
-```
-
-The reference checker validates syntax and duplicate identifiers without network
-resolution. A human must still compare every identifier and quotation with the opened
-source. Follow NLM *Citing Medicine* or the current official style required by the
-venue [SW-S20, SW-S21].
-
-### 8. Validate authorship and disclosure
-
-Use journal criteria for authorship. Record the standardized CRediT roles as
-contribution metadata; CRediT does not itself define authorship [SW-S19].
-
-If AI was used, humans must verify all affected content and disclose the tool and
-purpose according to current journal and publisher policy. ICMJE's January 2026
-Recommendations require transparency and retain human accountability [SW-S01, SW-S02].
-
-```bash
-python3 scripts/validate_authorship.py authorship.json
-```
-
-Do not generate a disclosure from assumptions. See
-`references/authorship_ai_confidentiality.md`.
-
-### 9. Review declarations and open-science statements
-
-Verify each statement independently:
-
-- ethics and consent;
-- registration and protocol;
-- funding and sponsor role;
-- conflicts and relationships;
-- author contributions and acknowledgments;
-- data, code, materials, and protocol availability;
-- AI use.
-
-Be as open as rights and responsibilities permit, but do not expose confidential,
-personal, proprietary, licensed, or protected information. Record actual access
-conditions. See `references/research_integrity_open_science.md`.
-
-### 10. Use figures and tables only when warranted
-
-Figures and tables are optional and provenance-bound. This skill does not generate
-images or schematics.
-
-For every retained display:
-
-- link source data, code, transformations, and evidence IDs;
-- reconcile values with prose and registries;
-- document image processing, permissions, and licenses;
-- include units, denominators, sample sizes, uncertainty, and analysis population;
-- provide alt text and redundant non-color cues;
-- perform a manual accessibility and scientific check at final size.
-
-See `references/figures_tables.md`.
-
-### 11. Record non-scoring guideline coverage
-
-Record each bundled high-level topic as addressed, not applicable with rationale, or
-missing:
-
-```bash
-python3 scripts/select_reporting_guidelines.py check reporting_coverage.json
-```
-
-Then complete the official checklist using actual manuscript locations. Never claim
-adherence merely because the local coverage file passes.
-
-### 12. Lint and approve
-
-```bash
-python3 scripts/validate_manifest.py manuscript_manifest.json --kind manuscript
-python3 scripts/lint_manuscript.py manuscript.md \
-  --manifest manuscript_manifest.json
-```
-
-The linter reports issue codes and line numbers without echoing manuscript text.
-Sensitive-content warnings require manual review and are not a de-identification
-certificate.
-
-Only accountable humans may:
-
-- resolve scientific ambiguities;
-- approve author order and declarations;
-- approve external disclosure or transfer;
-- set `submission_ready` to true;
-- remove the draft banner;
-- authorize submission.
-
-## Revision and peer review
-
-Treat reviewer material as confidential. Do not upload it to an external service without
-the required authorization and policy review [SW-S01, SW-S24].
-
-For each requested change:
-
-1. record the comment without exposing it outside the approved boundary;
-2. classify it as editorial, scientific, statistical, policy, or unresolved;
-3. identify affected claims, evidence, methods, results, and displays;
-4. revise the registries before prose when facts change;
-5. re-run every affected audit;
-6. draft a response that states what changed and where;
-7. obtain human approval.
-
-Do not comply with a request that would fabricate, hide, overstate, or breach policy.
-
-## Current policy caution
-
-COPE's 2017 Core Practices were retired in 2024. As of 2026-07-24, COPE announced that
-a replacement Code of Conduct would be published in 2026; do not describe the archived
-Core Practices as current membership standards [SW-S04, SW-S05]. Distinguish formal
-COPE positions from discussion documents, webinars, comments, and case advice.
-
-## Formatting and submission
-
-The former LaTeX assets were removed because a generic polished template could allow
-plausible placeholders to ship. Use the Markdown scaffold and structured records.
-Apply the target venue's current controlled template only after verification.
-
-See:
-
-- `assets/REPORT_FORMATTING_GUIDE.md`
-- `references/professional_report_formatting.md`
-- `references/journal_policies.md`
-
-Formatting cannot convert an incomplete evidence record into a submission-ready paper.
-
-## Bundled files
-
-### Assets
-
-- `assets/manuscript_scaffold.md`
-- `assets/manuscript_manifest_template.json`
-- `assets/source_manifest_template.json`
-- `assets/claim_evidence_template.csv`
-- `assets/consistency_manifest_template.json`
-- `assets/authorship_template.json`
-- `assets/reporting_coverage_template.json`
-- `assets/reporting_guidelines.json`
-
-### Scripts
-
-- `scripts/scaffold_manuscript.py`
-- `scripts/validate_manifest.py`
-- `scripts/select_reporting_guidelines.py`
-- `scripts/audit_claims.py`
-- `scripts/check_consistency.py`
-- `scripts/check_references.py`
-- `scripts/validate_authorship.py`
-- `scripts/lint_manuscript.py`
-
-All scripts are local, deterministic, bounded, dependency-free, and network-free. See
-`references/cli_reference.md`.
-
-### References
-
-- `references/evidence_workflow.md`
-- `references/writing_principles.md`
-- `references/imrad_structure.md`
-- `references/citation_styles.md`
-- `references/reporting_guidelines.md`
-- `references/figures_tables.md`
-- `references/authorship_ai_confidentiality.md`
-- `references/research_integrity_open_science.md`
-- `references/journal_policies.md`
-- `references/professional_report_formatting.md`
-- `references/cli_reference.md`
-- `references/source_ledger.md`