From 7e4a14f560661eb4f82ee2681073229a620cdd00 Mon Sep 17 00:00:00 2001 From: nzy1997 Date: Mon, 21 Sep 2026 09:31:56 +0800 Subject: [PATCH 1/2] Scope writing context and verify document builds --- skills/how-to-technical-writing/SKILL.md | 8 +- skills/how-to-technical-writing/checklist.md | 10 +-- skills/how-to-write-ideas-report/SKILL.md | 20 ++--- .../references/writing-workflow.md | 73 ++++++++++++++----- tests/test_writing_workflow.py | 57 +++++++++++++++ 5 files changed, 129 insertions(+), 39 deletions(-) create mode 100644 tests/test_writing_workflow.py diff --git a/skills/how-to-technical-writing/SKILL.md b/skills/how-to-technical-writing/SKILL.md index c263ec7..c70dc28 100644 --- a/skills/how-to-technical-writing/SKILL.md +++ b/skills/how-to-technical-writing/SKILL.md @@ -9,8 +9,8 @@ Keep the working directory at the user's project. Resolve this `SKILL.md` with `Path(path).resolve()` to follow symlinks. Bare `helpers/`, `references/`, and template paths are relative to that real directory. `skills//...` refers to the installed skill found by public name in the agent's catalog, not the -user's project. Dependencies need not be siblings; report and install missing -skills before the dependent step. Shared writing files are bundled in +user's project. Dependencies need not be siblings; report a missing required skill before +its dependent step. Shared writing files are bundled in `how-to-write-ideas-report/references/`. # Writing style guide @@ -56,7 +56,7 @@ Clarity outranks these rules. When they conflict, keep the clearer sentence. ## Hunt table -Use for reviews and final language passes. Each finding cites its row; leave passages that match none untouched. **Comment only** fixes remain comments even after approval; the author writes the replacement. +Use for reviews and final language passes. Each finding cites its row; leave passages that match none untouched. **Comment only** fixes remain comments within a language pass. A separately requested substantive revision needs its own evidence and scope; approval to polish does not authorize changing a claim. | Hunt for | Fix | |---|---| @@ -83,6 +83,6 @@ Use for reviews and final language passes. Each finding cites its row; leave pas - **Change wording, never meaning.** Preserve definitions, theorems, claims, and field terms. Never add or remove a claim, figure, or derivation step as a language fix. - **Recheck every number, count, and qualifier** in each rewritten sentence before continuing. -- **Comment on content changes; do not apply them.** This includes changing quantifiers or hedges, adding missing justifications, deleting paragraphs as digressions, or removing "not X but Y" contrasts. Use `[reviewer]` comments: `% [reviewer]` in LaTeX, `// [reviewer]` in Typst, or HTML comments in Markdown. The author writes the replacement. +- **Comment on content changes; do not apply them.** This includes changing quantifiers or hedges, adding missing justifications, deleting paragraphs as digressions, or removing "not X but Y" contrasts. Use `[reviewer]` comments: `% [reviewer]` in LaTeX, `// [reviewer]` in Typst, or HTML comments in Markdown. Resolve these as a separate substantive revision only when requested and supported by evidence. - **Leave passing passages alone.** Every proposed rewrite names its rule; never rewrite merely to produce a diff. - **Prose rules never require figure detail.** Conceptual and overview figures may omit implementation and timing details. Use the Figure Rulebook in `write-paper` to judge figures against their stated purpose. Flag omissions only if they materially misrepresent the central mechanism or contradict a claim attributed to the figure. Prefer clarifying labels, captions, or nearby prose; weigh added graphics against readability. Diagrams need not depict every mechanism discussed in the text. diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index edd127d..1e53bbb 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -1,6 +1,6 @@ # Writing checklist -The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `write-paper` language pass or a `review-paper` writing pass. The five sections below group items by topic; their numbers are not the guideline numbers in `review-paper/SKILL.md`. Sentence structure and wording cover guideline 1; paragraph focus and information flow bring together items from guidelines 1, 3, and 4; definitions and notation cover guideline 2; equations and figures bring together items from guidelines 1, 5, and 7. Guidelines 2, 5, and 7 apply the `write-paper` Notation and Figure Rulebooks. See `skills/write-paper/references.md` for the reasoning. Guidelines 6, 8, and 9 are review process and live in `skills/review-paper/checklist.md`. +The checkable form of the rules in `SKILL.md`. Apply only items relevant to the requested scope; the guide's meaning-preservation rules take precedence over shorthand here. Use it as the checklist for a `write-paper` language pass or a `review-paper` writing pass. The five sections below group items by topic; their numbers are not the guideline numbers in `review-paper/SKILL.md`. Sentence structure and wording cover guideline 1; paragraph focus and information flow bring together items from guidelines 1, 3, and 4; definitions and notation cover guideline 2; equations and figures bring together items from guidelines 1, 5, and 7. Guidelines 2, 5, and 7 apply the `write-paper` Notation and Figure Rulebooks. See `skills/write-paper/references.md` for the reasoning. Guidelines 6, 8, and 9 are review process and live in `skills/review-paper/checklist.md`. --- @@ -9,7 +9,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr - [ ] No sentence introduces multiple new ideas at once. Long compound sentences are split. - [ ] Do not use concepts that target reader are not familiar with to explaining a concept - [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. -- [ ] Sentences run about 8-25 words. No semicolon chains, “and … so …” chains, paired em-dash asides, or paired-comma appositives. +- [ ] Sentence length is a signal, not a target. Split overloaded clauses while retaining logical links; do not enforce a fixed word count. - [ ] A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. ## 2 — Wording and tone @@ -18,7 +18,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr - [ ] No content-free openers, "Notice that", or empty meta-talk. Signposts that name a section's job or point to a result stay. - [ ] Simple words are used and every technical word is kept. No verb, quantifier, or adjective is swapped inside a mathematical statement. - [ ] No metaphor. -- [ ] Avoid “X, not Y”. State X directly. +- [ ] Remove an unmotivated contrast only when meaning is preserved; retain contrasts that express the result. Content changes remain comments in a language pass. - [ ] Replace vague abstract nouns (“property,” “system,” “structure,” ...) with the specific concept they refer to. - [ ] Use literal verbs. Do not use metaphorical verbs (“unlock”, “bridge”, "open", ...). @@ -40,7 +40,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr ## 4 — Definitions and notation -- [ ] A symbol and notation table was built while reading. +- [ ] Definitions and uses of symbols in the reviewed scope are consistent; build a notation table when it helps track them. - [ ] No symbol or concept is used before it is defined. No forward references. - [ ] No symbol is left never defined. - [ ] No term or symbol is defined before the argument needs it. Every definition is used later. @@ -50,7 +50,7 @@ The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `wr ## 5 — Equations and figures -- [ ] Do not use inline calculations. Use a display instead. +- [ ] Combine runs of inline computation into a display when it improves clarity; keep short routine algebra inline when no emphasis is needed. - [ ] Display equations are reserved for flagship results, non-obvious steps, key intermediates, or equations referenced by a figure. - [ ] Routine algebra that fits inline is not promoted to a display equation. - [ ] No equation with a referenced label is proposed for inlining or cutting. In a letter, algebra moves to the supplement rather than losing a reproducibility step. diff --git a/skills/how-to-write-ideas-report/SKILL.md b/skills/how-to-write-ideas-report/SKILL.md index cd2af35..4c179ae 100644 --- a/skills/how-to-write-ideas-report/SKILL.md +++ b/skills/how-to-write-ideas-report/SKILL.md @@ -5,14 +5,11 @@ description: Agentic trigger. Use when writing a proposal-style ideas report fro ## Installed resources -Keep the working directory at the user's project. Resolve this loaded `SKILL.md` -with `Path(path).resolve()` before locating resources; follow symlinks. Bare -`helpers/`, `references/`, and template paths are relative to that real skill -directory. A path written as `skills//...` means the installed `` -skill's directory from the agent's skill catalog, not a path in the user's project. -Locate each dependency by its public skill name; copied skills need not be siblings. -If a dependency is absent, report the missing skill and install it before that step. -Shared writing files are bundled in `how-to-write-ideas-report/references/`. +Keep the working directory at the user's project. Resolve this `SKILL.md` to its +real path before locating bundled resources. `skills//...` refers to the +installed skill found by public name, not the user's project; dependencies need +not be siblings. Load only resources needed for the current task. If a required +dependency is missing, report it before that dependent step. **Path conventions:** `docs/discussion/` and `articles/` resolve from the **project working directory**; resource paths follow Installed resources above. @@ -26,13 +23,16 @@ Write a structured ideas report after a `brainstorm-ideas` session has converged Follow `skills/how-to-technical-writing/SKILL.md` for sentence- and paragraph-level prose rules. Follow `skills/how-to-write-ideas-report/references/writing-workflow.md` for context loading, citation handling, gap-filling research, output format, diagrams, and finish checks. - Primary source: `docs/discussion/*-brainstorm-ideas-log.md`. If multiple logs exist and the request does not identify one, ask which to use. -- If no log exists, ask the user to brainstorm first or describe the chosen direction and reasoning to preserve. +- If no log exists, use the chosen direction and reasoning already in the conversation or supplied notes. Ask only for substance needed to write the requested report. - Save to `articles/YYYY-MM-DD--ideas-report.{md,typ,tex}` with a matching bibliography when citations are used. - When entering from `brainstorm-ideas` Phase 3, carry forward the active conversation log, user profile, chosen direction, key references, and concrete action plan without asking the user to repeat them. ### Report structure -Draft each section, show it, and incorporate feedback: +With a chosen direction and supporting material, draft the complete report and +verify it before presenting it for review. Use section-by-section feedback only +when the user requests collaborative drafting or an unresolved substantive +choice prevents a coherent draft. Include the relevant parts below: - **Research Question** — one sentence - **Novelty Claim** — what is new and why it matters diff --git a/skills/how-to-write-ideas-report/references/writing-workflow.md b/skills/how-to-write-ideas-report/references/writing-workflow.md index 1d092c9..b7529a3 100644 --- a/skills/how-to-write-ideas-report/references/writing-workflow.md +++ b/skills/how-to-write-ideas-report/references/writing-workflow.md @@ -6,11 +6,19 @@ Resolve the installed `how-to-download-ref` skill from the agent's catalog and s ## Context -- Resolve the project KB with `KB=$(python3 "$DOWNLOAD_REF_DIR/helpers/resolve_kb.py")`. -- If present, read `$KB/NOTES.md`, `$KB/INDEX.md`, and the canonical bib `$KB/references.bib`. -- Read `docs/discussion/user-profile.md` when audience, background, or positioning matters. -- For ideas/manuscripts, read relevant `docs/discussion/*-brainstorm-ideas-log.md`. -- If the needed literature base is missing, suggest the `survey` skill or ask the user for explicit source files. +Start with the user's supplied text, source files, scope, format, and existing +authorization. A local prose edit needs the passage and its relevant definitions +or citations, not the whole literature library or conversation history. + +- Resolve the project KB only when KB-backed context is needed, using + `KB=$(python3 "$DOWNLOAD_REF_DIR/helpers/resolve_kb.py")`. +- Search INDEX.md/NOTES.md for the topic, then read relevant notes and bibliography + entries. Full bibliographic screening belongs to an explicitly selected review. +- Read `docs/discussion/user-profile.md` when audience or positioning matters; + read only relevant brainstorming logs, starting with their wrap-up sections. +- Supplied papers and a manuscript-local bibliography are valid source material + without a sci-brain KB. Fill evidence gaps within the requested task, asking + only for missing substance that cannot be established from the sources. The canonical bib is `$KB/references.bib`. @@ -18,13 +26,13 @@ The canonical bib is `$KB/references.bib`. ## Scope the source set -A write-up covers a *subset* of the bib — the references the relevant `NOTES.md` section(s) actually cite, not all 100+ accumulated entries. Determine that subset deterministically instead of by eye: +For a KB-backed report, a write-up covers a *subset* of the bib — the references the relevant `NOTES.md` section(s) actually cite, not all 100+ accumulated entries. Determine that subset deterministically instead of by eye: ```sh python3 "$DOWNLOAD_REF_DIR/helpers/scope_refs.py" --notes "$KB/NOTES.md" --bib "$KB/references.bib" ``` -It prints the scoped cite keys (one per line) and exits non-zero if any `[@key]` anchor in the notes has no bib entry — fix dangling anchors before drafting. Use `--json` for `{scoped, missing, unused}`. Draft against the scoped keys; the `unused` list is out of scope unless the user asks to widen it. +When the user supplied explicit sources instead, use those directly; do not require NOTES.md. The helper prints the scoped cite keys (one per line) and exits non-zero if any `[@key]` anchor in the notes has no bib entry — fix dangling anchors before drafting. Use `--json` for `{scoped, missing, unused}`. Draft against the scoped keys; the `unused` list is out of scope unless the user asks to widen it. ## References @@ -37,15 +45,17 @@ It prints the scoped cite keys (one per line) and exits non-zero if any `[@key]` Search only for gaps needed to support the document's main claims. Prefer the active KB first, then MCP/Semantic Scholar/arXiv/CrossRef/web search. Stop when the main claims have citations; completeness is not the goal. -**Recency gate — decide whether to search at all.** Read the build date in the `NOTES.md` header. If it is recent (≲ 4 weeks old), the literature base is fresh: skip discovery gap-filling entirely and only resolve *citation-level* gaps (a claim in the draft with no key to back it). Only when `NOTES.md` is older — or absent — run the recency search for SOTA results, active groups, and method families that may have superseded the notes. +**Search according to the claim.** A recent NOTES.md can avoid repeating discovery, +but its date does not establish that a volatile or SOTA claim is current. Verify +such claims when the document relies on them or the user requests an update. +Stable derivations and local language edits do not require a new field survey. ## Output Format -Check `CLAUDE.md`/`AGENTS.md` for a configured format. Otherwise ask: - -- Typst (`.typ`) — recommended when no venue template overrides it -- LaTeX (`.tex`) — traditional academic format -- Markdown (`.md`) — fastest, but citations remain inline unless rendered elsewhere +Reuse the user's format, the existing document, or the project's configured +format. For a new standalone report with no convention, use Markdown. Use the +venue's format when required, and Typst or LaTeX when requested or needed for a +PDF. Ask only when the choice affects a requirement that remains unresolved. ## Figures And Diagrams @@ -59,13 +69,36 @@ For Typst, prefer native `grid` + `rect` + fixed-width `box()` for text-heavy la ## Finish -Run these checks before declaring the document done — do not eyeball them: +Verify the requested output, not an unrelated full workflow: + +- **Compile changed document source** and inspect the result when producing a + final PDF. A plain Markdown or inline-text request needs only its relevant + rendering/text checks; report when no build applies. +- **Check both exit status and citation diagnostics.** For Typst, run from the + document directory (replace `main.typ` with the actual source): -- **Compile** the document (`typst compile .typ`, or the LaTeX/Markdown equivalent) and confirm it exits cleanly. -- **No dangling citations.** Grep the compile log for unresolved-reference warnings; for Typst, a missing key warns rather than errors, so an empty grep is the pass condition: ```sh - typst compile .typ 2>&1 | grep -i "unresolved\|warning" || echo "clean" + BUILD_LOG=$(mktemp) + if typst compile main.typ >"$BUILD_LOG" 2>&1; then + cat "$BUILD_LOG" + else + cat "$BUILD_LOG" >&2 + rm -f "$BUILD_LOG" + exit 1 + fi + if grep -Ei 'unresolved|warning' "$BUILD_LOG"; then + rm -f "$BUILD_LOG" + exit 1 + fi + rm -f "$BUILD_LOG" ``` -- **Every scoped claim is cited.** Confirm each `@key` in the prose resolves to a bib entry and that no scoped key was silently dropped (cross-check against `scope_refs.py` output). -- **Non-empty bibliography** renders in the output. -- Report the output path and any skipped verification. + + A warning requires inspection before declaring completion; do not classify a + failed compiler as clean merely because its error lacks the word “warning”. +- **Citations:** verify each used key resolves and that sources support the main + claims. A selected paper need not be cited when it does not support the final + argument. If citations are used, ensure the bibliography renders; do not + require one for an uncited excerpt. +- Fix failures introduced by the requested changes and rerun affected checks. + Stop after they pass unless a concrete unresolved finding requires more work. +- Deliver the requested artifact with verification and any remaining limitations. diff --git a/tests/test_writing_workflow.py b/tests/test_writing_workflow.py new file mode 100644 index 0000000..62a5c07 --- /dev/null +++ b/tests/test_writing_workflow.py @@ -0,0 +1,57 @@ +"""Execute the documented Typst build check against realistic outcomes.""" + +import os +import re +import subprocess +from pathlib import Path + +import pytest + + +ROOT = Path(__file__).resolve().parents[1] + + +@pytest.mark.parametrize( + "compiler_exit,diagnostic,expected_exit", + [ + (0, "", 0), + (0, "warning: unresolved citation", 1), + (2, "error: unknown variable", 1), + (127, "compiler unavailable", 1), + ], +) +def test_documented_compile_check_handles_failure_and_warnings( + tmp_path, compiler_exit, diagnostic, expected_exit +): + workflow = ( + ROOT / "skills/how-to-write-ideas-report/references/writing-workflow.md" + ).read_text() + blocks = re.findall(r"```sh\n(.*?)\n\s*```", workflow, re.DOTALL) + checks = [block for block in blocks if "typst compile" in block] + assert len(checks) == 1 + + compiler = tmp_path / "typst" + compiler.write_text( + '#!/bin/sh\nprintf "%s\\n" "$TEST_DIAGNOSTIC" >&2\n' + 'exit "$TEST_COMPILER_EXIT"\n' + ) + compiler.chmod(0o755) + logs = tmp_path / "logs" + logs.mkdir() + env = { + **os.environ, + "PATH": str(tmp_path) + os.pathsep + os.environ["PATH"], + "TMPDIR": str(logs), + "TEST_DIAGNOSTIC": diagnostic, + "TEST_COMPILER_EXIT": str(compiler_exit), + } + result = subprocess.run( + ["/bin/sh", "-c", checks[0]], + cwd=tmp_path, + env=env, + capture_output=True, + text=True, + ) + assert result.returncode == expected_exit, result + assert diagnostic in result.stdout + result.stderr + assert not list(logs.iterdir()), "temporary compiler log was not removed" From 3bb1c65332926972e486240e3a5b1d9097d53e48 Mon Sep 17 00:00:00 2001 From: GiggleLiu Date: Wed, 23 Sep 2026 14:10:28 +0800 Subject: [PATCH 2/2] Narrow to context scoping and the compile-check fix Drop the style-guide and checklist rule changes, the drafting-mode change, the recency-gate removal, and the output-format default change; those are separate decisions. Keep the shared "Installed resources" block identical across skills. Rewrite the Typst check without `exit` so it is safe to paste into an interactive shell; it still fails on a nonzero exit or any warning. Co-Authored-By: Claude Fable 5.1 --- skills/how-to-technical-writing/SKILL.md | 8 +- skills/how-to-technical-writing/checklist.md | 10 +-- skills/how-to-write-ideas-report/SKILL.md | 18 ++--- .../references/writing-workflow.md | 78 +++++++------------ 4 files changed, 45 insertions(+), 69 deletions(-) diff --git a/skills/how-to-technical-writing/SKILL.md b/skills/how-to-technical-writing/SKILL.md index c70dc28..c263ec7 100644 --- a/skills/how-to-technical-writing/SKILL.md +++ b/skills/how-to-technical-writing/SKILL.md @@ -9,8 +9,8 @@ Keep the working directory at the user's project. Resolve this `SKILL.md` with `Path(path).resolve()` to follow symlinks. Bare `helpers/`, `references/`, and template paths are relative to that real directory. `skills//...` refers to the installed skill found by public name in the agent's catalog, not the -user's project. Dependencies need not be siblings; report a missing required skill before -its dependent step. Shared writing files are bundled in +user's project. Dependencies need not be siblings; report and install missing +skills before the dependent step. Shared writing files are bundled in `how-to-write-ideas-report/references/`. # Writing style guide @@ -56,7 +56,7 @@ Clarity outranks these rules. When they conflict, keep the clearer sentence. ## Hunt table -Use for reviews and final language passes. Each finding cites its row; leave passages that match none untouched. **Comment only** fixes remain comments within a language pass. A separately requested substantive revision needs its own evidence and scope; approval to polish does not authorize changing a claim. +Use for reviews and final language passes. Each finding cites its row; leave passages that match none untouched. **Comment only** fixes remain comments even after approval; the author writes the replacement. | Hunt for | Fix | |---|---| @@ -83,6 +83,6 @@ Use for reviews and final language passes. Each finding cites its row; leave pas - **Change wording, never meaning.** Preserve definitions, theorems, claims, and field terms. Never add or remove a claim, figure, or derivation step as a language fix. - **Recheck every number, count, and qualifier** in each rewritten sentence before continuing. -- **Comment on content changes; do not apply them.** This includes changing quantifiers or hedges, adding missing justifications, deleting paragraphs as digressions, or removing "not X but Y" contrasts. Use `[reviewer]` comments: `% [reviewer]` in LaTeX, `// [reviewer]` in Typst, or HTML comments in Markdown. Resolve these as a separate substantive revision only when requested and supported by evidence. +- **Comment on content changes; do not apply them.** This includes changing quantifiers or hedges, adding missing justifications, deleting paragraphs as digressions, or removing "not X but Y" contrasts. Use `[reviewer]` comments: `% [reviewer]` in LaTeX, `// [reviewer]` in Typst, or HTML comments in Markdown. The author writes the replacement. - **Leave passing passages alone.** Every proposed rewrite names its rule; never rewrite merely to produce a diff. - **Prose rules never require figure detail.** Conceptual and overview figures may omit implementation and timing details. Use the Figure Rulebook in `write-paper` to judge figures against their stated purpose. Flag omissions only if they materially misrepresent the central mechanism or contradict a claim attributed to the figure. Prefer clarifying labels, captions, or nearby prose; weigh added graphics against readability. Diagrams need not depict every mechanism discussed in the text. diff --git a/skills/how-to-technical-writing/checklist.md b/skills/how-to-technical-writing/checklist.md index 1e53bbb..edd127d 100644 --- a/skills/how-to-technical-writing/checklist.md +++ b/skills/how-to-technical-writing/checklist.md @@ -1,6 +1,6 @@ # Writing checklist -The checkable form of the rules in `SKILL.md`. Apply only items relevant to the requested scope; the guide's meaning-preservation rules take precedence over shorthand here. Use it as the checklist for a `write-paper` language pass or a `review-paper` writing pass. The five sections below group items by topic; their numbers are not the guideline numbers in `review-paper/SKILL.md`. Sentence structure and wording cover guideline 1; paragraph focus and information flow bring together items from guidelines 1, 3, and 4; definitions and notation cover guideline 2; equations and figures bring together items from guidelines 1, 5, and 7. Guidelines 2, 5, and 7 apply the `write-paper` Notation and Figure Rulebooks. See `skills/write-paper/references.md` for the reasoning. Guidelines 6, 8, and 9 are review process and live in `skills/review-paper/checklist.md`. +The checkable form of the rules in `SKILL.md`. Use it as the checklist for a `write-paper` language pass or a `review-paper` writing pass. The five sections below group items by topic; their numbers are not the guideline numbers in `review-paper/SKILL.md`. Sentence structure and wording cover guideline 1; paragraph focus and information flow bring together items from guidelines 1, 3, and 4; definitions and notation cover guideline 2; equations and figures bring together items from guidelines 1, 5, and 7. Guidelines 2, 5, and 7 apply the `write-paper` Notation and Figure Rulebooks. See `skills/write-paper/references.md` for the reasoning. Guidelines 6, 8, and 9 are review process and live in `skills/review-paper/checklist.md`. --- @@ -9,7 +9,7 @@ The checkable form of the rules in `SKILL.md`. Apply only items relevant to the - [ ] No sentence introduces multiple new ideas at once. Long compound sentences are split. - [ ] Do not use concepts that target reader are not familiar with to explaining a concept - [ ] Parallel grammar appears only where the ideas already run in parallel. No prose is turned into lists. -- [ ] Sentence length is a signal, not a target. Split overloaded clauses while retaining logical links; do not enforce a fixed word count. +- [ ] Sentences run about 8-25 words. No semicolon chains, “and … so …” chains, paired em-dash asides, or paired-comma appositives. - [ ] A sentence that wraps a display equation or binds a hypothesis to its conclusion stays whole. ## 2 — Wording and tone @@ -18,7 +18,7 @@ The checkable form of the rules in `SKILL.md`. Apply only items relevant to the - [ ] No content-free openers, "Notice that", or empty meta-talk. Signposts that name a section's job or point to a result stay. - [ ] Simple words are used and every technical word is kept. No verb, quantifier, or adjective is swapped inside a mathematical statement. - [ ] No metaphor. -- [ ] Remove an unmotivated contrast only when meaning is preserved; retain contrasts that express the result. Content changes remain comments in a language pass. +- [ ] Avoid “X, not Y”. State X directly. - [ ] Replace vague abstract nouns (“property,” “system,” “structure,” ...) with the specific concept they refer to. - [ ] Use literal verbs. Do not use metaphorical verbs (“unlock”, “bridge”, "open", ...). @@ -40,7 +40,7 @@ The checkable form of the rules in `SKILL.md`. Apply only items relevant to the ## 4 — Definitions and notation -- [ ] Definitions and uses of symbols in the reviewed scope are consistent; build a notation table when it helps track them. +- [ ] A symbol and notation table was built while reading. - [ ] No symbol or concept is used before it is defined. No forward references. - [ ] No symbol is left never defined. - [ ] No term or symbol is defined before the argument needs it. Every definition is used later. @@ -50,7 +50,7 @@ The checkable form of the rules in `SKILL.md`. Apply only items relevant to the ## 5 — Equations and figures -- [ ] Combine runs of inline computation into a display when it improves clarity; keep short routine algebra inline when no emphasis is needed. +- [ ] Do not use inline calculations. Use a display instead. - [ ] Display equations are reserved for flagship results, non-obvious steps, key intermediates, or equations referenced by a figure. - [ ] Routine algebra that fits inline is not promoted to a display equation. - [ ] No equation with a referenced label is proposed for inlining or cutting. In a letter, algebra moves to the supplement rather than losing a reproducibility step. diff --git a/skills/how-to-write-ideas-report/SKILL.md b/skills/how-to-write-ideas-report/SKILL.md index 4c179ae..2753f26 100644 --- a/skills/how-to-write-ideas-report/SKILL.md +++ b/skills/how-to-write-ideas-report/SKILL.md @@ -5,11 +5,14 @@ description: Agentic trigger. Use when writing a proposal-style ideas report fro ## Installed resources -Keep the working directory at the user's project. Resolve this `SKILL.md` to its -real path before locating bundled resources. `skills//...` refers to the -installed skill found by public name, not the user's project; dependencies need -not be siblings. Load only resources needed for the current task. If a required -dependency is missing, report it before that dependent step. +Keep the working directory at the user's project. Resolve this loaded `SKILL.md` +with `Path(path).resolve()` before locating resources; follow symlinks. Bare +`helpers/`, `references/`, and template paths are relative to that real skill +directory. A path written as `skills//...` means the installed `` +skill's directory from the agent's skill catalog, not a path in the user's project. +Locate each dependency by its public skill name; copied skills need not be siblings. +If a dependency is absent, report the missing skill and install it before that step. +Shared writing files are bundled in `how-to-write-ideas-report/references/`. **Path conventions:** `docs/discussion/` and `articles/` resolve from the **project working directory**; resource paths follow Installed resources above. @@ -29,10 +32,7 @@ Follow `skills/how-to-technical-writing/SKILL.md` for sentence- and paragraph-le ### Report structure -With a chosen direction and supporting material, draft the complete report and -verify it before presenting it for review. Use section-by-section feedback only -when the user requests collaborative drafting or an unresolved substantive -choice prevents a coherent draft. Include the relevant parts below: +Draft each section, show it, and incorporate feedback: - **Research Question** — one sentence - **Novelty Claim** — what is new and why it matters diff --git a/skills/how-to-write-ideas-report/references/writing-workflow.md b/skills/how-to-write-ideas-report/references/writing-workflow.md index b7529a3..8cd409d 100644 --- a/skills/how-to-write-ideas-report/references/writing-workflow.md +++ b/skills/how-to-write-ideas-report/references/writing-workflow.md @@ -6,19 +6,15 @@ Resolve the installed `how-to-download-ref` skill from the agent's catalog and s ## Context -Start with the user's supplied text, source files, scope, format, and existing -authorization. A local prose edit needs the passage and its relevant definitions -or citations, not the whole literature library or conversation history. - -- Resolve the project KB only when KB-backed context is needed, using - `KB=$(python3 "$DOWNLOAD_REF_DIR/helpers/resolve_kb.py")`. -- Search INDEX.md/NOTES.md for the topic, then read relevant notes and bibliography - entries. Full bibliographic screening belongs to an explicitly selected review. -- Read `docs/discussion/user-profile.md` when audience or positioning matters; - read only relevant brainstorming logs, starting with their wrap-up sections. -- Supplied papers and a manuscript-local bibliography are valid source material - without a sci-brain KB. Fill evidence gaps within the requested task, asking - only for missing substance that cannot be established from the sources. +Start from what the user supplied: text, source files, scope, format, and any +authorization already given. A local prose edit needs the passage plus the +definitions and citations it depends on, not the whole KB or conversation history. + +- Resolve the project KB when KB-backed context is needed: `KB=$(python3 "$DOWNLOAD_REF_DIR/helpers/resolve_kb.py")`. +- Read `$KB/INDEX.md` and `$KB/NOTES.md` for the topic, then the relevant notes and bibliography entries. Screening the whole bibliography belongs to an explicitly selected review. +- Read `docs/discussion/user-profile.md` when audience, background, or positioning matters. +- For ideas/manuscripts, read the relevant `docs/discussion/*-brainstorm-ideas-log.md`, starting from the wrap-up section. +- Papers the user supplied and a manuscript-local bibliography are valid sources without a sci-brain KB. If the needed literature base is missing, suggest the `survey` skill or ask the user for explicit source files. The canonical bib is `$KB/references.bib`. @@ -45,17 +41,15 @@ When the user supplied explicit sources instead, use those directly; do not requ Search only for gaps needed to support the document's main claims. Prefer the active KB first, then MCP/Semantic Scholar/arXiv/CrossRef/web search. Stop when the main claims have citations; completeness is not the goal. -**Search according to the claim.** A recent NOTES.md can avoid repeating discovery, -but its date does not establish that a volatile or SOTA claim is current. Verify -such claims when the document relies on them or the user requests an update. -Stable derivations and local language edits do not require a new field survey. +**Recency gate — decide whether to search at all.** Read the build date in the `NOTES.md` header. If it is recent (≲ 4 weeks old), the literature base is fresh: skip discovery gap-filling entirely and only resolve *citation-level* gaps (a claim in the draft with no key to back it). Only when `NOTES.md` is older — or absent — run the recency search for SOTA results, active groups, and method families that may have superseded the notes. ## Output Format -Reuse the user's format, the existing document, or the project's configured -format. For a new standalone report with no convention, use Markdown. Use the -venue's format when required, and Typst or LaTeX when requested or needed for a -PDF. Ask only when the choice affects a requirement that remains unresolved. +Check `CLAUDE.md`/`AGENTS.md` for a configured format. Otherwise ask: + +- Typst (`.typ`) — recommended when no venue template overrides it +- LaTeX (`.tex`) — traditional academic format +- Markdown (`.md`) — fastest, but citations remain inline unless rendered elsewhere ## Figures And Diagrams @@ -69,36 +63,18 @@ For Typst, prefer native `grid` + `rect` + fixed-width `box()` for text-heavy la ## Finish -Verify the requested output, not an unrelated full workflow: - -- **Compile changed document source** and inspect the result when producing a - final PDF. A plain Markdown or inline-text request needs only its relevant - rendering/text checks; report when no build applies. -- **Check both exit status and citation diagnostics.** For Typst, run from the - document directory (replace `main.typ` with the actual source): +Run these checks before declaring the document done — do not eyeball them: +- **Compile** the document and check both the exit status and the log. For Typst, a missing cite key only warns, so a clean exit alone is not a pass; the block below fails on a nonzero exit *or* on any warning, and prints the log either way (replace `main.typ` with the source file): ```sh - BUILD_LOG=$(mktemp) - if typst compile main.typ >"$BUILD_LOG" 2>&1; then - cat "$BUILD_LOG" - else - cat "$BUILD_LOG" >&2 - rm -f "$BUILD_LOG" - exit 1 - fi - if grep -Ei 'unresolved|warning' "$BUILD_LOG"; then - rm -f "$BUILD_LOG" - exit 1 - fi - rm -f "$BUILD_LOG" + LOG=$(mktemp) + typst compile main.typ >"$LOG" 2>&1; status=$? + cat "$LOG" + grep -Eiq 'unresolved|warning' "$LOG" && status=1 + rm -f "$LOG" + [ "$status" -eq 0 ] && echo clean ``` - - A warning requires inspection before declaring completion; do not classify a - failed compiler as clean merely because its error lacks the word “warning”. -- **Citations:** verify each used key resolves and that sources support the main - claims. A selected paper need not be cited when it does not support the final - argument. If citations are used, ensure the bibliography renders; do not - require one for an uncited excerpt. -- Fix failures introduced by the requested changes and rerun affected checks. - Stop after they pass unless a concrete unresolved finding requires more work. -- Deliver the requested artifact with verification and any remaining limitations. + Use the LaTeX/Markdown equivalent for other formats. Read every warning before calling the build clean. +- **Every scoped claim is cited.** Confirm each `@key` in the prose resolves to a bib entry and that no scoped key was silently dropped (cross-check against `scope_refs.py` output). +- **Non-empty bibliography** renders in the output. +- Report the output path and any skipped verification.