Improve note quality contracts and lint gates

Author: 917Dhj

SKILL.md

@@ -64,7 +64,31 @@ Follow this order:
 7. build the synthesis bundle
 8. have Codex/GPT read the bundle and write the note
 9. lint the final note
-10. write into Obsidian
+10. perform `final_readability_review` after lint passes
+11. write into Obsidian
+
+This is the required workflow for a normal single-paper note request, not a loose suggestion.
+Unless this skill explicitly marks a stage as optional, required stages must not be silently skipped, reordered into a shortcut, or treated as complete just because a partial artifact already exists.
+
+Global no-short-circuit rule:
+- do not stop after only the early stages and present the workflow as finished
+- do not treat slowness, inconvenience, or temporary uncertainty as permission to bypass a required stage
+- do not replace the declared workflow with an improvised shortcut
+- if a required stage fails, only do one of three things:
+  - retry that stage
+  - enter a fallback that is explicitly allowed by this skill
+  - stop and report which stage is blocked and which downstream required stages remain incomplete
+- do not describe the whole task as complete while required downstream stages are still pending
+
+Completion-language rule:
+- say `笔记已完成` only when the required workflow is actually complete
+- say `已生成草稿` when drafting is done but lint, final readability review, or save is still pending
+- say `已通过校验` only when lint has actually been run and passed
+- say `已保存到 Obsidian` only when the write step has actually succeeded
+- do not treat `lint 已通过` as equivalent to `整篇笔记已经润色完成`
+- if final readability review is still pending, explicitly say the draft passed script lint but has not finished final language review
+- if the workflow stopped early, name the current stage and the still-missing required stages instead of using completion language
+- lint is a floor, not the writing objective
 
 Read [references/workflow.md](references/workflow.md) for the full pipeline and data contracts.
 Read [references/architecture.md](references/architecture.md) for the separation between the reusable core workflow and the Codex-specific adapter layer.
@@ -97,6 +121,7 @@ then switch into setup-assistant mode:
 5. if Codex can directly help complete a missing configuration, offer that next
 
 In setup-assistant mode, prefer a practical environment report over generic documentation text.
+The no-short-circuit rules above apply to normal note-generation requests, not to this setup-assistant mode.
 
 ## Tool and Source Priority
 
@@ -120,16 +145,26 @@ Zotero-first rule:
 ## Output Rules
 
 - The default output is a Markdown note written into the Obsidian vault when configured.
-- If no Obsidian vault is configured, DeepPaperNote should fall back to saving into the current workspace instead of failing outright.
+- Workspace fallback is allowed only when no Obsidian vault is configured at all.
+- If an Obsidian vault is configured, DeepPaperNote must treat that vault as the required save target rather than silently switching output roots.
+- If the configured vault or its paper-local subdirectories are outside the current writable scope, DeepPaperNote must ask the user for permission escalation instead of downgrading to workspace output.
+- If the user refuses that permission escalation, DeepPaperNote must clearly report that the note has not been saved into Obsidian yet.
+- After such a refusal, DeepPaperNote may save to the workspace only if it asks again and receives explicit user consent for that fallback.
 - By default, each paper should be written into its own same-name folder, with the note and images stored together.
 - The note should never default to the bare `20_Research/Papers` root. Choose a domain folder first.
 - Domain selection should be conservative: prefer an existing domain folder in the user's vault when there is a reasonable match; only create a new domain folder when no existing domain fits well.
 - A normal note-generation request should complete in one pass: note text, figure placeholder decisions, image materialization when confident, and final save.
 - Do not stop after a text-only draft just to ask whether the user wants figures inserted. Finish the figure replacement decision inside the same task unless the user explicitly asked for text only.
 - Always create the paper-local `images/` folder during final save, even if no high-confidence images were materialized.
+- The `images/` folder is part of the required save protocol, not an optional cleanup step. If permission is missing, request it; do not skip the directory.
+- Do not present a workspace write as if the Obsidian save already succeeded.
 - The note must use real heading levels: `#`, `##`, and `###`.
-- The note should include `原始摘要` near the beginning when abstract metadata is available, before `一句话总结`.
-- When abstract metadata is available, `原始摘要` should normally contain both the English original and a Chinese translation.
+- The note should include `原文摘要翻译` near the beginning when abstract metadata is available, before `一句话总结`.
+- When abstract metadata is available, `原文摘要翻译` should directly translate the original paper abstract into Chinese rather than restating it as your own summary.
+- The `原文摘要翻译` section itself should be Chinese-only; do not place English abstract sentences or English paragraph excerpts in that section.
+- Do not mix later judgments, innovation summaries, or hindsight explanations into `原文摘要翻译`; keep it as the original abstract translated into Chinese.
+- The note should include a dedicated `创新点` section immediately after `原文摘要翻译` and before `一句话总结`.
+- The `创新点` section should not be empty praise. It should enumerate the paper's actual innovations and briefly explain why each one matters.
 - High-quality notes should usually contain multiple meaningful `###` subheadings in the technical sections when the paper is non-trivial.
 - The note must include figure/table placeholders for all major visuals rather than silently skipping them.
 - Real images may replace some placeholders, but only if they clearly match the corresponding paper figure/table.
@@ -148,6 +183,9 @@ Model-first rule:
 - if formulas, objectives, or complexity expressions are central, include the key ones in the final note
 - render math as `$...$` or `$$...$$`, not as inline code or fenced code blocks
 - before final save, explicitly self-review whether the note contains enough technical detail, key numbers, and any necessary formulas
+- after script lint passes, reread the full note once more for readability; do not stop at formal compliance only
+- in that final readability review, ordinary English phrase leftovers should usually be rewritten into natural Chinese, while stable proper nouns may remain in English
+- do not use the final readability review to invent new facts, empty filler text, or shallower but safer wording just to satisfy lint
 
 Use [references/note-quality.md](references/note-quality.md) for quality checks.
 Use [references/paper-types.md](references/paper-types.md) for domain adaptation.

assets/note_template.md

@@ -16,6 +16,10 @@
 - 领域:
 - 论文类型:
 
+## 原文摘要翻译
+
+## 创新点
+
 ## 一句话总结
 
 ## 研究问题
@@ -24,6 +28,8 @@
 
 ## 方法主线
 
+### 机制流程
+
 ## 关键结果
 
 ## 深度分析
@@ -33,4 +39,3 @@
 ## 我的笔记
 
 ## 引用
-

references/deep-analysis.md

@@ -126,8 +126,17 @@ Explain:
 - what the training target or optimization target really is
 - how inference or sampling actually proceeds
 - which implementation details matter for reproducing the claimed gain
+- even if an extracted Algorithm block is broken, reconstruct the mechanism in plain engineering language rather than giving up
+- make the reader feel the Input -> key transformation -> Output flow, not just the paper's terminology
+
+For method, framework, or system papers:
+- default to an explicit `### 机制流程` subsection inside `方法主线`
+- write it as a 3 to 4 step numbered list rather than a long paragraph
+- each step should say what goes in, what operation happens, and where the output goes next
+- if the paper has both training and inference details, use `### 机制流程` for the dominant execution chain and leave training recipe details to neighboring subsections
 
 For complex papers, use `###` subheadings such as:
+- `### 机制流程`
 - `### 数据构建`
 - `### 中间表征抽取`
 - `### 模型结构`
@@ -146,6 +155,8 @@ Include:
 For method papers, also ask:
 - does the result support the claimed mechanism
 - is the gain internal-only or external too
+- if the paper reports ablations or removed-module comparisons, include at least one setting that hurt performance, made training unstable, or revealed a trade-off
+- if the evidence bundle contains no such negative ablation signal, say explicitly that the paper did not clearly report failed or unstable settings
 
 ### 深度分析
 
@@ -192,6 +203,7 @@ Seed future follow-up with prompts such as:
 When the paper has useful visuals:
 - preserve placeholders for the important ones
 - prioritize one method figure, one data/task figure, and one result figure or table
+- if a high-confidence pipeline or architecture figure clearly matches the core execution chain, place it in `### 机制流程` first
 - explain why each figure matters
 - keep original paper numbering such as `Fig. 1` or `Table 2`
 
@@ -209,6 +221,8 @@ Typical cases where a formula should appear:
 - scaling-law fit
 
 Prefer a few stable, well-explained formulas over many noisy ones.
+- after each retained formula, add one short engineering explanation of what it means in implementation terms
+- do not stop at naming variables; explain what operation, objective term, or state update the formula corresponds to
 
 ## Minimum Honesty Standard
 

references/figure-placement.md

@@ -17,7 +17,8 @@ Priority order:
 
 ## Placement Logic
 
-- Put method overview figures in `方法主线`
+- Put method overview figures in `### 机制流程` when they directly explain the core execution chain
+- If the match is weaker or the note does not need that micro-structure, keep them in `方法主线`
 - Put data or task figures in `数据与任务定义`
 - Put main result figures or tables in `关键结果`
 - Put conceptual diagrams in `研究问题` or `深度分析` if they clarify the argument

references/final-writing.md

@@ -14,18 +14,35 @@ Then draft the final note in natural language.
 
 Near the beginning of the note, include:
 - `## 核心信息`
-- `## 原始摘要`
+- `## 原文摘要翻译`
+- `## 创新点`
 - `## 一句话总结`
 
-The `原始摘要` section should preserve the paper's original abstract in readable Chinese note context:
-- if the abstract is available, include it before the one-sentence summary
+`## 核心信息` is a fixed metadata block, not an analysis block.
+Rules for this section:
+- only use the predefined metadata-style fields from the note template
+- keep each line in `- 字段名: 值` form
+- do not add ad hoc fields such as judgments, takeaways, or mini-summaries
+- do not move explanatory prose, evaluation, or "my view" sentences into this section
+- if a field is unavailable, leave it blank or mark it as not clearly available rather than replacing the field with commentary
+
+The `原文摘要翻译` section should be a Chinese translation of the paper's original abstract:
+- if the abstract is available, translate the original abstract into Chinese before the one-sentence summary
 - do not let the summary replace the abstract
-- the summary should explain the paper's real value, while the abstract section preserves the author's original framing
-- do not stop at only the English abstract
-- inside this section, prefer:
-  - `### 英文原文`
-  - `### 中文翻译`
-- the Chinese translation should be fluent and faithful, not a second “一句话总结”
+- do not treat `原文摘要翻译` as your own summary of the full paper; it is the original abstract translated into Chinese
+- do not split this section into `### 英文原文` and `### 中文翻译`
+- keep the section title exactly as `原文摘要翻译`
+- the `原文摘要翻译` section itself must be written in Chinese; do not output English abstract sentences or English-original paragraphs here
+- the Chinese abstract should be fluent and faithful, not a second “一句话总结”
+- do not turn `原文摘要翻译` into a selective excerpt or a compressed highlight list
+- do not add judgments, hindsight, or details learned from later sections of the paper into `原文摘要翻译`; only translate what the original abstract says
+
+The `创新点` section should be a dedicated top-level section after `原文摘要翻译` rather than a hidden bullet buried later.
+It should usually:
+- enumerate 3 to 5 paper-specific innovations
+- explain what problem each innovation addresses
+- explain what new capability, mechanism, or evaluation angle it enables
+- avoid generic praise such as “the paper is novel” without locating the novelty
 
 ## Writer Persona
 
@@ -88,6 +105,26 @@ The final Chinese note must also pass a language-cleanliness check:
 - no half-English half-Chinese prose lines
 - English is allowed only for stable proper nouns or citation metadata
 - if the style gate fails, do not write the note into Obsidian yet
+- do not write for the linter; lint is only a minimum floor, not the writing objective
+- after script lint passes, `final_readability_review` is still required before the note should be treated as polished and ready to save
+
+正文术语策略:
+- default to natural Chinese prose in正文分析
+- keep English only when it is a stable proper noun or source-faithful technical label
+- stable English that may remain:
+  - model names
+  - dataset names
+  - metric names
+  - method names
+  - math symbols
+  - code tokens
+  - original paper figure/table ids
+- English that should usually be rewritten into natural Chinese:
+  - ordinary English phrases
+  - abstract descriptive phrases in analytical prose
+  - leftover English wording that has no clear reason to remain
+- when a first mention benefits from both forms, prefer Chinese-first wording with an English gloss in parentheses
+- do not leave phrases such as `reasoning dataset`, `distillation risk`, or `reward model quality` directly inside Chinese prose when a natural Chinese rendering is available
 
 For non-trivial papers, the note should usually not stop at only broad `##` sections.
 It should use meaningful `###` subheadings where they improve technical clarity.
@@ -105,12 +142,23 @@ Examples:
 - `### 哪些地方容易被误读`
 
 For technical papers, also strongly consider subsections such as:
+- `### 机制流程`
 - `### 训练目标`
 - `### 推理与采样链路`
 - `### 关键实现细节`
 - `### 复杂度与扩展性`
 - `### 消融到底说明了什么`
 
+For method, framework, and system papers, prefer an explicit `### 机制流程` subsection instead of hiding the execution chain inside generic prose.
+That subsection should usually be a 3 to 4 step numbered list covering:
+- what the Input is
+- what the main intermediate transformations are
+- what the Output is
+- what the training or inference loop is actually doing
+- do not rely on a damaged Algorithm block to carry this explanation for you
+- do not let the steps collapse into module-name listing; each step should describe an operation
+- if a high-confidence pipeline or architecture figure matches this execution chain, place it in `### 机制流程`
+
 ## Formula Rule
 
 Do not avoid formulas by default.
@@ -127,6 +175,10 @@ Use formulas sparingly and purposefully:
 - each formula should help explain the method
 - do not dump many formulas just to look technical
 - if the source extraction is noisy, prefer reconstructing a small, stable core formula rather than copying broken math verbatim
+- after each retained formula, add one sentence explaining what it corresponds to in engineering or code terms
+- do not only translate variable names; explain the concrete operation, loss term, update rule, or control effect
+- formulas in the final Markdown should be written as directly renderable Obsidian/MathJax math, not as JSON-style escaped strings
+- do not double-escape TeX commands such as `\\tau`, `\\frac`, `\\bar`, `\\begin`, or `\\end` when the final note should contain `\tau`, `\frac`, `\bar`, `\begin`, or `\end`
 - use real math delimiters:
   - inline math: `$...$`
   - display math: `$$ ... $$`
@@ -179,7 +231,22 @@ Before outputting the final Markdown, explicitly check:
 - does the note contain concrete numbers, dimensions, complexity terms, or formulas when the paper clearly depends on them?
 - can a reader familiar with Python and deep learning frameworks follow the core method from this note alone?
 - does the method section explain the mechanism rather than only summarize the claim?
+- if this is a method/system/framework paper, does `方法主线` explicitly contain `### 机制流程` with a 3 to 4 step numbered list?
+- if the evidence bundle contains negative or unstable ablation signals, did the note include at least one of them?
+- if the evidence bundle does not contain such signals, did the note explicitly say the paper did not clearly report failed or unstable settings?
 - does the note contain at least one honest limitation and one paper-specific insight?
 - are there any suspicious mid-sentence line breaks left in the prose?
+- after script lint passes, have you reread the full note once more for readability rather than stopping at "lint passed"?
+- are there still any stiff translations, awkward Chinese phrasing, or ordinary English phrases that should be rewritten into natural Chinese?
+- are there any lines that sound like they were written only to satisfy lint or section compliance rather than to help a real reader?
+- if the note includes LaTeX formulas, did you quickly check that the final Markdown uses directly renderable TeX rather than double-escaped commands or broken math delimiters?
+
+This final readability review is a language-and-expression pass, not a second evidence-judgment pass:
+- improve fluency and readability
+- remove stiff translations
+- convert ordinary English phrase leftovers into natural Chinese
+- keep stable proper nouns when forcing a translation would sound worse
+- do not invent new facts, numbers, comparisons, or failure cases during this pass
+- do not use polish as an excuse to flatten the note into a safer but shallower summary
 
 If the answer to the first three questions is "no", the draft is still too shallow and should be revised before save.