@lylll9436/paper-polish-workflow-skill 2.1.0

package/references/repo-patterns.md

@@ -0,0 +1,96 @@
+# Repo Scan Patterns
+
+Scan heuristics for categorizing files in Python ML experiment repositories and mapping them to academic paper sections.
+
+Scope: Python ML projects only (v2.0). Non-Python repo support deferred per ADVR-01.
+
+## Quick Reference
+
+| Category | Primary Section | Key File Types |
+|---|---|---|
+| documentation | Introduction | README.md, docs/**/*.md |
+| config | Methods | *.yaml, *.yml, *.toml, *.json |
+| results | Results and Discussion | results/**/*.csv, metrics.json |
+| code | Methods | *.py, src/**/*.py, *.ipynb |
+| figures | Results and Discussion | figures/**/*.png, plots/**/*.* |
+| dependencies | Methods | requirements.txt, pyproject.toml |
+
+## File Identification Patterns
+
+| Glob | Category | Priority | Notes |
+|---|---|---|---|
+| `README.md`, `README.rst`, `README.txt` | documentation | 1 | Primary project description; highest priority |
+| `docs/**/*.md` | documentation | 1 | Extended documentation |
+| `*.yaml`, `*.yml`, `*.json`, `*.toml` | config | 2 | Hyperparameters, experiment settings |
+| `*.ini`, `*.cfg`, `.env.example`, `Makefile` | config | 2 | Build and environment configuration |
+| `results/**/*.csv`, `results/**/*.json` | results | 3 | Tabular experiment outputs |
+| `results/**/*.xlsx`, `results/**/*.tsv` | results | 3 | Spreadsheet experiment outputs |
+| `logs/**/*.log` | results | 3 | Training and evaluation logs |
+| `*.csv` (root only), `metrics.json`, `scores.json` | results | 3 | Root-level result summaries |
+| `*.py`, `src/**/*.py`, `scripts/**/*.py` | code | 4 | Source code and scripts |
+| `*.ipynb` | code | 4 | Notebooks (see Ambiguity Rules) |
+| `figures/**/*.png`, `figures/**/*.jpg` | figures | 5 | Static visualizations |
+| `figures/**/*.svg`, `figures/**/*.pdf` | figures | 5 | Vector and PDF figures |
+| `plots/**/*.*` | figures | 5 | Plot output directory |
+| `*.png`, `*.jpg`, `*.svg` (root only) | figures | 5 | Root-level images |
+| `requirements.txt`, `setup.py`, `setup.cfg` | dependencies | 6 | Python packaging and dependencies |
+| `pyproject.toml`, `Pipfile` | dependencies | 6 | Modern Python packaging |
+| `environment.yml`, `conda.yml` | dependencies | 6 | Conda environment specification |
+
+Priority 1 = highest specificity. When a file matches multiple categories, use the lowest priority number (most specific wins).
+
+## Category to Paper Section Mapping
+
+| Category | Primary Section | Secondary Section | Notes |
+|---|---|---|---|
+| documentation | Introduction | Methods | README often describes both motivation and approach |
+| config | Methods | - | Hyperparameters, model architecture choices, experiment settings |
+| results | Results and Discussion | - | Tables, metrics, evaluation outputs |
+| code | Methods | - | Algorithm implementation details, model architecture |
+| figures | Results and Discussion | - | Visualizations of findings, plots |
+| dependencies | Methods | - | Technology stack, reproducibility information |
+
+## Ambiguity Rules
+
+- **Jupyter notebooks** (`*.ipynb`): categorize as "code" by default. If located in `results/`, `figures/`, or `output/` directory, categorize by directory instead
+- **Multiple category matches**: use the lowest priority number (most specific wins)
+- **Hidden files and directories** (`.*`): skip entirely
+- **Test files** (`test_*`, `*_test.py`, `tests/`): skip -- not relevant to paper content
+- **Data files** (`*.h5`, `*.pkl`, `*.npy`, `*.pt`, `*.pth`): skip -- binary data, not directly readable for outline generation
+- **`pyproject.toml` overlap**: matches both config (Priority 2) and dependencies (Priority 6). Categorize as dependencies -- its primary role is package specification
+
+## Scan Depth
+
+Scan root directory and one level of subdirectories (top 2 levels). Deeper paths require explicit user specification.
+
+Directory names that indicate relevant content at the first subdirectory level:
+
+| Directory | Expected Content |
+|---|---|
+| `src/` | Core source code modules |
+| `scripts/` | Utility and execution scripts |
+| `results/` | Experiment output data and metrics |
+| `figures/` | Generated visualizations and plots |
+| `logs/` | Training and evaluation logs |
+| `data/` | Dataset references (skip binary files) |
+| `models/` | Model definitions or saved checkpoints |
+| `notebooks/` | Jupyter notebooks for exploration |
+| `experiments/` | Experiment configurations and runs |
+| `docs/` | Extended project documentation |
+| `plots/` | Plot output files |
+
+## Skip Rules
+
+Files and directories to exclude from scan:
+
+- Hidden files and directories (names starting with `.`)
+- `__pycache__/`, `*.pyc`, `*.pyo` -- Python bytecode
+- `node_modules/`, `.venv/`, `venv/`, `env/` -- virtual environments
+- `.git/` -- version control internals
+- `test_*`, `*_test.py`, `tests/` -- test files (not paper-relevant)
+- Binary data files: `*.h5`, `*.pkl`, `*.npy`, `*.pt`, `*.pth`, `*.bin`
+
+---
+
+*Reference: references/repo-patterns.md*
+*Conventions: references/skill-conventions.md*

package/references/skill-conventions.md

@@ -0,0 +1,273 @@
+# Skill Conventions
+
+Canonical authoring rules for all Claude Code Skills in this project.
+
+Every new Skill must follow this document. The companion example skeleton at [`references/skill-skeleton.md`](skill-skeleton.md) provides a copyable starting point that encodes these rules.
+
+---
+
+## Frontmatter Contract
+
+Every `SKILL.md` must begin with a YAML frontmatter block containing these fields:
+
+### Required Fields
+
+| Field | Type | Purpose | Example |
+|-------|------|---------|---------|
+| `name` | string | Unique Skill identifier. Must match parent directory name. Max 64 chars, pattern `^[a-z0-9]+(-[a-z0-9]+)*$` | `translation-skill` |
+| `description` | string | Brief description including trigger keywords. Max 1024 chars | `Translate Chinese academic text into polished English for journal submission` |
+| `triggers` | object | Discovery metadata with `primary_intent` (string) and `examples` (list of phrases) | See skeleton |
+| `tools` | list | Tools the Skill is allowed to depend on by default. Use capability names, not vendor-specific identifiers | `[Read, Write]` |
+| `references` | object | `required` (list of stable entrypoint paths) and optional `leaf_hints` (list of narrower modules) | See skeleton |
+| `input_modes` | list | Accepted input shapes | `[file, pasted_text]` |
+| `output_contract` | list | Output types the Skill produces | `[polished_english, latex]` |
+
+### Rules
+
+- Keep frontmatter concise. Operational detail belongs in the body sections, not in repeated prose fields.
+- `triggers.examples` should include both English and Chinese phrases when the Skill supports bilingual invocation.
+- `tools` lists capability categories (Read, Write, Structured Interaction, PDF Analysis) rather than hard-coding one vendor tool name. If a Skill needs structured user interaction, list `Structured Interaction` and define the fallback in the body.
+- `references.required` lists stable entrypoint files. `references.leaf_hints` lists narrower modules the Skill is likely to need, but the Skill may still load other leaf files at runtime.
+
+---
+
+## Body Structure
+
+The Skill body uses a semi-templated backbone. All sections below are required unless marked optional.
+
+| Section | Required | Purpose |
+|---------|----------|---------|
+| `## Purpose` | Yes | One-paragraph summary of what the Skill does and who it serves |
+| `## Trigger` | Yes | When and how the Skill activates, including example invocations |
+| `## Modes` | Yes | Supported interaction modes and how behavior varies across them |
+| `## References` | Yes | Which reference files the Skill loads and under what conditions |
+| `## Ask Strategy` | Yes | What to ask the user before acting and how to handle missing information |
+| `## Workflow` | Yes | Step-by-step operational flow; depth varies by Skill type |
+| `## Output Contract` | Yes | Exact shape of what the Skill produces |
+| `## Edge Cases` | Yes | Known tricky inputs and how to handle them |
+| `## Fallbacks` | Yes | Degradation behavior when tools or references are unavailable |
+| `## Examples` | Recommended | At least one minimal invocation-and-output example |
+
+### Section Depth
+
+- **Direct Skills** (e.g., caption generation): Keep Workflow short. A numbered list of 3-5 steps is enough.
+- **Guided Skills** (e.g., paper polishing): Workflow may use sub-headings for each phase, but must still respect the line budget.
+
+### Bilingual Output Eligibility
+
+Skills are classified as bilingual-eligible based on their `output_contract` type. Skills that produce academic text support bilingual paragraph-by-paragraph comparison; pure analysis, recommendation, and citation Skills are exempt.
+
+| Eligibility | Skills | Reason |
+|-------------|--------|--------|
+| Eligible (default ON) | translation, polish, de-ai, reviewer-simulation, abstract, experiment, logic | Produces academic text where Chinese comparison aids the user |
+| Exempt | caption, cover-letter, visualization, literature | English-only captions, journal-specific format, recommendation-only, BibTeX output |
+
+Eligible Skills support bilingual paragraph-by-paragraph comparison output. Bilingual mode is ON by default; users may opt out. The bilingual format specification is defined in `references/bilingual-output.md` (created in Phase 13).
+
+---
+
+## Reference Loading Rules
+
+Skills must follow the project's stable-entrypoint-plus-leaf-module architecture.
+
+### Loading Strategy
+
+1. If the Skill knows exactly which leaf module it needs, it may load that leaf file directly.
+2. If the Skill is unsure, it must start from the stable overview entrypoint and select the appropriate leaf from there.
+3. Never duplicate reference content into `SKILL.md`. Load it at runtime.
+
+### Declaring References
+
+- List all stable entrypoints in frontmatter `references.required`.
+- List likely leaf files in `references.leaf_hints` so maintainers know which narrow modules the Skill expects to use.
+- If a loaded reference does not match the current task, stop and ask the user for clarification rather than silently guessing a fallback.
+- **`required: []` is acceptable** only for self-contained Skills that produce no written academic text and load no local reference files by design. Qualifying cases: pure analysis Skills (e.g., `logic-skill` — logic checking), pure recommendation Skills (e.g., `visualization-skill` — chart type suggestions), and external-MCP-only Skills (e.g., `literature-skill` — literature search). The `## References` body section must document why no reference loading is needed.
+
+### Reference Paths
+
+- Expression patterns: `references/expression-patterns.md` (overview), `references/expression-patterns/*.md` (leaves)
+- Anti-AI patterns: `references/anti-ai-patterns.md` (overview), `references/anti-ai-patterns/*.md` (leaves)
+- Journal contracts: `references/journals/[journal].md`
+
+---
+
+## Interaction Modes
+
+Every Skill must declare which modes it supports and how behavior changes across them.
+
+### Mode Taxonomy
+
+| Mode | Behavior | When to Use |
+|------|----------|-------------|
+| `interactive` | Full step-by-step flow with user confirmation at each decision point | Default for guided Skills when the user wants maximum control |
+| `guided` | Multi-pass flow with user confirmation at key checkpoints, not every micro-step | When the user wants structure but not per-sentence confirmation |
+| `direct` | Single-pass output with minimal interaction | Quick-fix requests or batch processing |
+| `batch` | Process multiple inputs with the same settings, minimal per-item interaction | When applying the same operation across sections or files |
+
+### Mode Selection
+
+- The default mode should be stated in the `## Modes` section.
+- If the user does not specify a mode, use the default.
+- Mode can be inferred from trigger phrasing (e.g., "quickly polish" suggests `direct`; "help me revise step by step" suggests `interactive`).
+
+---
+
+## Fallback Rules
+
+Every Skill must define graceful degradation for at least these scenarios.
+
+### Structured Interaction Unavailable
+
+If the runtime environment does not provide a structured interaction tool (e.g., no `AskUserQuestion`, no `mcp_question`):
+
+1. Fall back to 1-3 plain-text questions covering only the highest-impact gaps.
+2. Do not block the entire workflow. Proceed with sensible defaults and explain what was assumed.
+3. Document the fallback in the `## Fallbacks` section.
+
+### Reference File Missing
+
+If a declared reference file cannot be loaded:
+
+1. Log which file was expected and could not be found.
+2. If the Skill can still produce useful output without the reference, proceed with reduced capability and warn the user.
+3. If the reference is critical to correctness, stop and tell the user what is missing.
+
+### Journal Not Specified
+
+If the Skill supports journal-aware behavior but the user does not specify a journal:
+
+1. Ask once which journal the paper targets.
+2. If the user declines or does not know, proceed with general academic style.
+3. Do not guess a journal.
+
+---
+
+## Line Budget
+
+`SKILL.md` files must stay lean. Target approximately 300 lines as a hard budget.
+
+### Why
+
+- Large Skills consume too much context before the real task begins.
+- Reference content belongs in `references/`, not inline.
+- Shorter Skills are easier to maintain, review, and evolve.
+
+### Rules
+
+- Target: 300 lines or fewer.
+- If a Skill exceeds 300 lines, the author must justify why the extra length is necessary and cannot be moved to a reference file.
+- Frontmatter counts toward the budget.
+- Comments and blank lines count toward the budget.
+
+### Strategies to Stay Under Budget
+
+- Move reusable tables, pattern lists, and examples to `references/`.
+- Keep Workflow steps concise; use sub-headings only when the Skill is genuinely multi-phase.
+- Avoid duplicating information that already exists in a reference file.
+
+---
+
+## Ask Strategy Conventions
+
+The default interaction posture for all Skills is **ask first, then act**.
+
+### What to Ask
+
+- Any input that materially changes the output direction (target journal, section scope, interaction mode).
+- Do not ask about things the Skill can safely infer or default.
+
+### How to Ask
+
+- When structured interaction is available, use it for multi-option questions.
+- When it is not available, ask 1-3 plain-text questions covering only the highest-impact gaps.
+- Never ask more than 3 questions before producing initial output.
+
+### When to Skip Asking
+
+- In `direct` and `batch` modes, reduce or eliminate pre-questions when the user has provided enough context in the trigger.
+- If all required information is already present in the input, proceed without asking.
+
+### AskUserQuestion Enforcement
+
+Each Skill's `## Ask Strategy` section declares which questions use `AskUserQuestion` and which use plain text. There is no blanket mandate — authors decide per-Skill based on interaction needs.
+
+**Rules:**
+
+- When `AskUserQuestion` is available and the user must choose between 2-4 discrete options, use it.
+- In `direct` mode, Skills skip all `AskUserQuestion` calls entirely. The user chose direct = they want speed. Proceed with defaults and inferred context.
+- In `batch` mode, `AskUserQuestion` calls are also skipped; settings from the first item apply to all subsequent items.
+- When `AskUserQuestion` is unavailable, fall back per the existing rule in `## Fallback Rules > Structured Interaction Unavailable`.
+
+**Good — structured question for multi-option selection:**
+
+```
+AskUserQuestion({
+  question: "Which section should I polish first?",
+  options: [
+    { label: "Abstract", description: "Full abstract rewrite with word count check" },
+    { label: "Introduction", description: "Logic flow and contribution statement" },
+    { label: "Methods", description: "Technical accuracy and reproducibility" }
+  ]
+})
+```
+
+**Bad — plain dialogue for multi-option questions:**
+
+```
+"Which section should I polish first?
+1. Abstract
+2. Introduction
+3. Methods
+Please type the number."
+```
+
+Do not present options as numbered plain text when `AskUserQuestion` is available. The structured tool provides a timed multiple-choice interface that is faster and less error-prone.
+
+---
+
+## Workflow Memory
+
+All Skills must participate in the project-wide workflow memory system. This system records Skill invocations and detects frequent sequences to offer workflow recommendations.
+
+### Recording
+
+- After the Skill's first-step validation completes (i.e., when the Skill begins producing output, not on invocation), append one entry to `.planning/workflow-memory.json`.
+- Entry format: `{"skill": "<skill-name>", "ts": "<ISO timestamp>"}`
+- Maximum 50 entries retained. If log length >= 50, drop the oldest entry before appending.
+- If the file does not exist, create it as `[]` before appending.
+- If the Skill refuses or exits before completing first-step validation, do NOT write a record.
+
+### Pattern Detection (Step 0)
+
+- At the very start of the Workflow, before any existing Step 1 logic, read `.planning/workflow-memory.json`.
+- Check if the last 1-2 entries form a consecutive pattern with the current Skill that appears >= threshold times (configured in `.planning/config.json` under `workflow_memory.threshold`, default: 5).
+- Pattern types: 2-item (A->B) or 3-item (A->B->C) consecutive chains. Check 3-item patterns first (more specific wins).
+- Count occurrences by scanning the entire log left-to-right: for each position i where log[i..i+N-1] matches the pattern, count +1. Occurrences may share no entries but positions can be non-overlapping.
+- If a matching pattern is found, present a bilingual recommendation via AskUserQuestion:
+  - Question: "检测到常用流程：[pattern]（已出现 N 次）。是否直接以 direct 模式运行 [current skill]？"
+  - Options: "Yes, proceed" (activates direct mode) / "No, continue normally"
+- If the user accepts: skip all Ask Strategy questions and run in `direct` mode.
+- If the user declines or AskUserQuestion is unavailable: proceed in normal mode.
+- Pattern detection must not block the workflow. If the history file is missing, empty, or unparseable, skip silently to Step 1.
+
+---
+
+## Naming and Discovery
+
+- Skill directory name must match the `name` field in frontmatter.
+- `description` must contain keywords that help discovery (both English and Chinese when applicable).
+- `triggers.examples` should cover common invocation phrases so the Skill is findable via natural language.
+
+---
+
+## Maintenance Rules
+
+- When updating a Skill, preserve the frontmatter contract. Do not remove required fields.
+- When adding a new reference dependency, add it to `references.required` or `references.leaf_hints`.
+- When conventions change, update this document first, then propagate to existing Skills.
+- Keep the example skeleton in sync with this document.
+
+---
+
+*Conventions: references/skill-conventions.md*
+*Companion skeleton: [references/skill-skeleton.md](skill-skeleton.md)*

package/references/skill-skeleton.md

@@ -0,0 +1,169 @@
+# Skill Skeleton
+
+A copyable starting point for new Claude Code Skills in this project.
+
+Copy this file, rename it to `SKILL.md` inside your new Skill directory, and fill in each section. See [`references/skill-conventions.md`](skill-conventions.md) for the full authoring rules.
+
+---
+
+```yaml
+---
+name: example-skill
+description: Brief description with trigger keywords. Include both English and Chinese phrases when applicable
+triggers:
+  primary_intent: what the skill does in one phrase
+  examples:
+    - "English trigger phrase"
+    - "Chinese trigger phrase"
+tools:
+  - Read
+  - Write
+  - Structured Interaction
+references:
+  required:
+    - references/expression-patterns.md
+    - references/journals/ceus.md
+  leaf_hints:
+    - references/expression-patterns/results-and-discussion.md
+input_modes:
+  - file
+  - pasted_text
+output_contract:
+  - polished_english
+  - latex
+---
+```
+
+## Purpose
+
+State what the Skill does in one paragraph. Include who the Skill serves and what the output is used for.
+
+> Example: This Skill translates Chinese academic drafts into polished English text ready for journal submission. It produces LaTeX-formatted output that preserves technical terminology and follows the target journal's style preferences.
+
+## Trigger
+
+Describe when the Skill activates and list example invocations.
+
+**Activates when the user asks to:**
+- [English trigger description]
+- [Chinese trigger description]
+
+**Example invocations:**
+- "Help me [action] my [target]"
+- "[Chinese equivalent]"
+
+## Modes
+
+| Mode | Default | Behavior |
+|------|---------|----------|
+| `interactive` | | Full step-by-step with confirmation at each decision |
+| `guided` | Yes | Multi-pass with confirmation at key checkpoints |
+| `direct` | | Single-pass output, minimal interaction |
+| `batch` | | Same operation across multiple inputs |
+
+**Default mode:** `guided`
+
+**Mode inference:** If the user says "quickly" or "just fix", switch to `direct`. If the user says "step by step" or "help me revise", use `interactive`.
+
+## References
+
+### Required (always loaded)
+
+| File | Purpose |
+|------|---------|
+| `references/expression-patterns.md` | Academic expression patterns overview |
+| `references/journals/ceus.md` | CEUS journal contract (when targeting CEUS) |
+
+### Leaf Hints (loaded when needed)
+
+| File | When to Load |
+|------|--------------|
+| `references/expression-patterns/results-and-discussion.md` | When working on results or discussion sections |
+
+### Loading Rules
+
+- Load required references at the start of the workflow.
+- Load leaf files only when the current task matches their scope.
+- If a reference file is missing, warn the user and proceed with reduced capability.
+- If the loaded reference does not match the current task, ask the user for clarification.
+
+## Ask Strategy
+
+**Before starting, ask about:**
+1. Target journal (if not already known)
+2. Which section or scope to work on
+3. Preferred interaction mode (if ambiguous from trigger)
+
+**Rules:**
+- Never ask more than 3 questions before producing initial output.
+- In `direct` mode, skip pre-questions if the user provided enough context.
+- Use structured interaction when available; fall back to plain-text questions otherwise.
+- See `skill-conventions.md > AskUserQuestion Enforcement` for when to use `AskUserQuestion` vs plain text.
+
+## Workflow
+
+### Step 0: Workflow Memory Check
+
+- Read `.planning/workflow-memory.json`. If file missing or empty, skip to Step 1.
+- Check if the last 1-2 entries form a recognized pattern with the current Skill (e.g., polish -> de-ai) that has appeared >= `workflow_memory.threshold` times (default: 5) in the log. See `skill-conventions.md > Workflow Memory > Pattern Detection` for the full algorithm.
+- If a pattern is found, present recommendation via AskUserQuestion:
+  - Question: "检测到常用流程：[pattern]（已出现 N 次）。是否直接以 direct 模式运行 [current skill]？"
+  - Options: "Yes, proceed" / "No, continue normally"
+- If user accepts: set mode to `direct` for this invocation, skip Ask Strategy questions.
+- If user declines or AskUserQuestion unavailable: continue in normal mode.
+
+### Step 1: Collect Context
+
+- Load required references.
+- Identify target journal and apply journal-specific constraints.
+- Read the user's input (file or pasted text).
+- **Record workflow:** After validation completes, append `{"skill": "example-skill", "ts": "<ISO timestamp>"}` to `.planning/workflow-memory.json`. If file does not exist, create as `[]` first. If log length >= 50, drop oldest entry before appending.
+
+### Step 2: [Primary Action]
+
+- [Describe the main operation the Skill performs]
+- [Present intermediate output for user review in `interactive` and `guided` modes]
+
+### Step 3: [Refinement]
+
+- [Describe any refinement, checking, or polishing step]
+- [In `direct` mode, this step runs automatically without user confirmation]
+
+### Step 4: Output
+
+- Present the final result.
+- Write to file after user confirmation (or automatically in `batch` mode).
+- Report word count and any journal constraint violations.
+
+## Output Contract
+
+| Output | Format | Condition |
+|--------|--------|-----------|
+| Polished text | Markdown or LaTeX | Always produced |
+| Word count | Integer | Always reported |
+| Journal compliance notes | Bullet list | When a target journal is specified |
+
+> **Bilingual eligibility:** If this Skill's `output_contract` produces academic text, it must support bilingual paragraph-by-paragraph comparison (ON by default). See `skill-conventions.md > Bilingual Output Eligibility` for the full classification.
+
+## Edge Cases
+
+| Situation | Handling |
+|-----------|----------|
+| Input is too short to analyze | Warn the user and offer to proceed with limited context |
+| Input language does not match expected language | Ask the user to confirm before proceeding |
+| Journal not in `references/journals/` | Proceed with general academic style; inform the user |
+| Multiple sections provided but scope unclear | Ask which section to process first |
+
+## Fallbacks
+
+| Scenario | Fallback |
+|----------|----------|
+| Structured interaction unavailable | Ask 1-3 plain-text questions covering the highest-impact gaps |
+| Reference file missing | Log the missing file, proceed with reduced capability, warn the user |
+| Target journal not specified | Ask once; if declined, use general academic style |
+| PDF analysis tool unavailable | Ask the user to paste relevant text instead of providing a PDF path |
+
+---
+
+*Skeleton: references/skill-skeleton.md*
+*Conventions: [references/skill-conventions.md](skill-conventions.md)*