paper-knowledge-workflow

# Paper Knowledge Workflow This skill is the workflow router for one traceable research-paper project. It manages the local knowledge base, project schema, source manifest, literature matrix, paper artifacts, evidence gates, and maintenance loop. It does not govern long-term multi-project knowledge bases or replace human scholarly judgment. For formal manuscript, article, thesis, report, or grant-proposal writing, it must route writing through the mandatory ARS writing gate below. ## First Response If the user is starting a project and has not supplied enough context, ask only these four questions: 1. What is the paper topic or working title? 2. What discipline or research type is this? 3. What materials do you already have? 4. What do you want from this session? Infer the entry state instead of asking the user to choose one: | Situation | Entry | |---|---| | Topic or direction only | `preflight` | | Sources, notes, bibliography, or source folders exist | `materials` | | A manuscript, section draft, or reviewer comments exist | `draft` | | Sources and draft both exist | `draft`, then repair manifest and claim map first | ## Workflow 1. `setup`: create or inspect the project layout and `SCHEMA.md`. 2. `ingest`: register sources in `index/source_manifest.json`; keep raw and processed material separate; use `process_pdfs.py` for PDFs when possible. 3. `map`: create source wiki notes through an LLM reading pass, then maintain `30_Matrix/literature_matrix.md`; use `generate_wiki.py` only to scaffold missing notes and matrix rows, then `validate_wiki.py` for deterministic coverage. 4. `question`: produce `40_Paper/research_question.md`; this is a strong checkpoint. 5. `outline`: prepare the paper structure and argument path. 6. `draft`: write or revise manuscript sections through the mandatory ARS writing gate. 7. `review`: run structure and evidence gates, then ARS integrity/review stages and scholarly review. 8. `maintain`: repair drift, stale sources, weak claims, and backlog items. Do not proceed from a broad topic directly to full manuscript drafting. The `research_question` checkpoint must be explicit before full drafting. ## Mandatory ARS Writing Gate Formal writing requires ARS. When the user asks to write, rewrite, reconstruct, substantially revise, review for submission, or produce a public-facing manuscript, article, thesis chapter, report, or grant proposal from project materials, use `academic-research-suite` as the writing pipeline, not as optional advice. Hard requirements when `academic-research-suite` is available: - Load `academic-research-suite`, then route through `ars/academic-pipeline/WORKFLOW.md` (`ars-full`) or the equivalent stage chain. - Keep this skill as project owner for source manifest, wiki, matrix, claim-evidence map, and deterministic gates. - Treat already completed external literature search or local source work as Stage 1 material; do not redo external discovery unless there is a documented gap. - Enter the ARS pipeline at the detected stage, but do not bypass mandatory ARS gates: Stage 2 writing, Stage 2.5 integrity, Stage 3 review, Stage 4/4' revision when needed, Stage 4.5 final integrity, and Stage 5 finalization. - Use ARS role prompts for substantive writing/revision/review phases. Do not replace them with an ordinary local draft pass. - Record the ARS stage path, skipped or pre-satisfied stages, and verification outcomes in the project paper folder, for example under `40_Paper/ars_full/`. ARS unavailable blocks full drafting. If `academic-research-suite` is not installed or cannot be loaded, stop before producing a formal full draft, state the blocker, and continue only if the user explicitly approves a degraded non-ARS draft. ## Required Artifacts The project contract is: ```text 00_Inbox/ 20_Sources/raw/ 20_Sources/processed/ 10_Wiki/ 10_Wiki/Sources/ 30_Matrix/literature_matrix.md 40_Paper/research_question.md 40_Paper/outline.md 40_Paper/draft.md 40_Paper/claim_evidence_map.md 50_Review/verification_report.md 50_Review/maintenance_report.md 50_Review/research_backlog.md index/source_manifest.json SCHEMA.md ``` ## References Load only the file needed for the current stage: - `references/workflow.md`: entry routing, stage outputs, and first-use guidance. - `references/schema.md`: directory contract, manifest fields, and claim map format. - `references/validation.md`: structure gate, evidence gate, maintenance, and review rules. - `references/ars-routing.md`: how to use `academic-research-suite` without vendoring or replacing it. ## Scripts Use the bundled scripts for deterministic setup, scaffolding, and gates: ```bash python3 skill/scripts/init_paper_project.py --root <project> --title "<title>" python3 skill/scripts/process_pdfs.py --root <project> --source-dir <project>/00_Inbox python3 skill/scripts/generate_wiki.py --root <project> python3 skill/scripts/validate_structure.py --root <project> python3 skill/scripts/validate_wiki.py --root <project> python3 skill/scripts/validate_evidence.py --root <project> python3 skill/scripts/generate_maintenance_report.py --root <project> ``` When installed as a skill, adjust the script path to the installed skill directory. `generate_wiki.py` is not a Wiki-content generator. It must only create missing source-note scaffolds and matrix rows, and it must preserve existing human- or LLM-authored source notes. The actual Wiki content should be produced by an LLM reading pass over the raw source and processed text, then reviewed before it supports claims. ## Validation Rules Hard gates: - Structure gate: required files and manifest schema must be present. - Wiki gate: manifest sources must have source wiki notes and local wikilinks must resolve. - Evidence gate: paragraph-level claims must cite usable manifest sources. - Parsed PDFs and scaffolded wiki notes are reading aids; they do not prove that a source has been read or can support a claim. - Scaffolded source notes are not valid literature synthesis. Do not treat a source wiki as complete until an LLM reading pass has filled summary, argument, method/corpus, evidence, relevance, claim candidates, and uncertainty fields. Soft gate: - Academic review can flag weak research questions, methods, literature coverage, or argument quality, but it must not claim automatic scholarly approval. ## Academic Research Suite `academic-research-suite` is mandatory for formal writing and substantial revision. Use `references/ars-routing.md` to determine the ARS entry stage. Keep this skill as the project owner and evidence gate.