tex-spec-writer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TeX Spec Writer

TeX规范编写技能

Use this skill to create or revise decision-complete TeX specs and phased implementation plans grounded in the actual repository state.

The goal is a durable artifact, not a chat-only plan. Every TeX source deliverable must come with a rendered PDF companion. The spec should let a later engineer implement, review, test, and validate the work without reconstructing missing decisions from the conversation.

使用该技能可基于代码仓库的实际状态，创建或修订决策完备的TeX规范以及分阶段实施计划。

我们的目标是生成可长期留存的工件，而非仅存在于对话中的方案。每个交付的TeX源文件都必须附带渲染好的PDF文件。该规范应能让后续工程师无需从对话中补全缺失的决策信息，即可直接开展实现、评审、测试和验证工作。

When To Use

使用场景

Use this skill when the user asks for:

a detailed spec in
```
.tex
```
a LaTeX implementation plan
an algorithm-heavy design document
a research-backed technical plan
a phased plan that should be checked into a repo
a rewrite or hardening pass on an existing TeX spec

Do not use this skill for short markdown plans, ordinary code review, or one-off explanation unless the user wants a TeX artifact.

使用该技能处理用户以下需求：

以
```
.tex
```
格式呈现的详细规范
LaTeX格式的实施计划
算法密集型设计文档
基于研究成果的技术方案
需要提交至代码仓库的分阶段方案
对现有TeX规范进行重写或强化

请勿将该技能用于简短的Markdown方案、常规代码评审或一次性解释，除非用户明确要求生成TeX格式的工件。

Core Workflow

核心工作流程

Clarify the deliverable
- Identify whether the user wants a new spec, a revision, or only a review.
- Treat a requested
```
.tex
```
  deliverable as requiring a companion
```
.pdf
```
  .
- If they ask for code implementation too, keep the TeX spec and implementation steps separate.
Find the canonical location
- Inspect the repo before choosing paths.
- Prefer existing plan/spec directories and naming conventions.
- Do not invent parallel doc trees when a canonical path exists.
Read the real source of truth
- Inspect current code, tests, README/docs, reports, prior specs, artifacts, and configs.
- Treat previous specs as references, not proof that the live repo matches them.
- If a report or existing TeX file is the user's source, read it directly.
Diagnose before writing
- State the actual problem the spec must solve.
- Push back if the requested angle is too narrow, stale, or aimed at the wrong failure mode.
- Identify what is in scope, out of scope, and already implemented.
Write a decision-complete TeX spec Include the sections that fit the task:
- Purpose
- Glossary for new readers, when the domain is specialized
- Current status and source evidence
- Problem diagnosis
- Product or system definition
- Goals and non-goals
- Canonical ownership boundaries
- Data/model/runtime contracts
- Required algorithms with LaTeX math or pseudocode
- Phased implementation plan
- File-level implementation map
- Test-driven development contract
- Metrics and promotion/acceptance rules
- Risks and failure modes
- Exact next sequence
- Exit rule
Make the spec implementable
- Prefer concrete constants, thresholds, states, interfaces, and acceptance criteria over broad intent.
- Include validation commands and expected artifacts, including the PDF path.
- Distinguish process completion from outcome success.
- Name what evidence would falsify or block the plan.
Validate TeX and render PDF
- Compile with the repo's existing command if one exists.
- Otherwise use
```
latexmk -pdf -interaction=nonstopmode -halt-on-error -outdir=<output-dir> <file>.tex
```
  when available.
- If
```
latexmk
```
  is unavailable, use
```
pdflatex -interaction=nonstopmode -halt-on-error -output-directory <output-dir> <file>.tex
```
  .
- Fix fatal errors before claiming the artifact is valid.
- Do not finish a TeX-writing pass without either producing the companion PDF or clearly reporting the compile blocker.
Clean artifacts
- Remove generated sidecars such as
```
.aux
```
  ,
```
.log
```
  ,
```
.out
```
  ,
```
.toc
```
  ,
```
.fls
```
  ,
```
.fdb_latexmk
```
  , and
```
.synctex.gz
```
  unless the repo intentionally tracks them.
- Always keep the rendered
```
.pdf
```
  next to the
```
.tex
```
  source, unless the repo has a stricter documented artifact location.
- Keep the
```
.tex
```
  source as the canonical artifact.
Handoff
- Report exact
```
.tex
```
  and
```
.pdf
```
  artifact paths.
- Report validation commands run and whether they passed.
- State any unresolved risks or manual next steps.

明确交付物
- 确认用户需求是创建新规范、修订现有规范还是仅进行评审。
- 若用户要求交付
```
.tex
```
  文件，则必须同时提供配套的
```
.pdf
```
  文件。
- 若用户同时要求代码实现，需将TeX规范与实现步骤分开处理。
确定标准存储位置
- 选择存储路径前先检查代码仓库。
- 优先使用现有的方案/规范目录及命名规则。
- 若已有标准路径，请勿创建平行的文档目录结构。
读取真实的权威数据源
- 检查当前代码、测试用例、README/文档、报告、先前的规范、工件及配置文件。
- 将先前的规范仅作为参考，而非认定当前代码仓库与规范一致的依据。
- 若用户指定以某份报告或现有TeX文件为数据源，直接读取该文件内容。
编写前先诊断
- 明确该规范需要解决的实际问题。
- 若用户需求的角度过于局限、过时或针对错误的故障模式，需提出异议。
- 明确需求的范围、非范围以及已实现的内容。
编写决策完备的TeX规范 根据任务需求包含以下相关章节：
- 目的
- 面向新读者的术语表（当涉及专业领域时）
- 当前状态及数据源依据
- 问题诊断
- 产品或系统定义
- 目标与非目标
- 标准职责边界
- 数据/模型/运行时契约
- 所需算法（含LaTeX数学公式或伪代码）
- 分阶段实施计划
- 文件级实现映射
- 测试驱动开发契约
- 指标及上线/验收规则
- 风险及故障模式
- 明确的后续执行步骤
- 终止规则
确保规范可落地实现
- 优先使用具体的常量、阈值、状态、接口及验收标准，而非宽泛的意图描述。
- 包含验证命令及预期工件，包括PDF文件的路径。
- 区分流程完成与结果成功。
- 明确哪些证据可否定或阻碍该计划的执行。
验证TeX并渲染PDF
- 若代码仓库已有编译命令，使用该命令进行编译。
- 若没有现有命令，且
```
latexmk
```
  可用，则使用命令：
```
latexmk -pdf -interaction=nonstopmode -halt-on-error -outdir=<output-dir> <file>.tex
```
- 若
```
latexmk
```
  不可用，则使用命令：
```
pdflatex -interaction=nonstopmode -halt-on-error -output-directory <output-dir> <file>.tex
```
- 在确认工件有效前，修复所有致命错误。
- 若未能生成配套PDF文件或未明确报告编译阻塞问题，则不得完成TeX编写工作。
清理工件
- 删除生成的辅助文件，如
```
.aux
```
  、
```
.log
```
  、
```
.out
```
  、
```
.toc
```
  、
```
.fls
```
  、
```
.fdb_latexmk
```
  及
```
.synctex.gz
```
  ，除非代码仓库有意跟踪这些文件。
- 始终将渲染好的
```
.pdf
```
  文件与
```
.tex
```
  源文件放在同一目录下，除非代码仓库有更严格的文档化工件存储位置要求。
- 将
```
.tex
```
  源文件作为权威工件留存。
交付工作
- 报告
```
.tex
```
  和
```
.pdf
```
  工件的准确路径。
- 报告执行的验证命令及执行结果是否通过。
- 说明任何未解决的风险或需手动执行的后续步骤。

Generalization Rules

通用规则

Keep domain facts out of the reusable workflow. Trading, math, product, backend, frontend, and research specs should use the same process but different evidence.
Use old specs as format examples only after verifying the current repo.
Do not preserve legacy commands, names, fields, or duplicate paths unless a real external boundary still consumes them.
If a canonical path replaces an old one, remove or clearly retire the old path when the task boundary allows it.

通用工作流程中不包含领域特定事实。交易、数学、产品、后端、前端及研究类规范均应遵循相同流程，但使用不同的依据数据。
仅在验证当前代码仓库后，才可将旧规范作为格式示例使用。
除非仍有实际外部依赖在使用，否则不得保留旧命令、旧名称、旧字段或重复路径。
若标准路径已替代旧路径，在任务范围允许的情况下，删除或明确停用旧路径。

Quality Bar

质量标准

A good TeX spec has enough detail that a future implementation pass can:

identify the exact files to change
write focused tests first
know the acceptance criteria
understand what not to build
run the validation commands
decide whether the work is done

A weak TeX spec usually lacks thresholds, file mapping, test strategy, or an exit rule. Tighten those before finishing.

一份优质的TeX规范应包含足够细节，以便后续实施人员能够：

确定需要修改的具体文件
优先编写针对性测试用例
明确验收标准
清楚哪些内容无需开发
执行验证命令
判断工作是否完成

一份质量不佳的TeX规范通常缺少阈值、文件映射、测试策略或终止规则。完成前需完善这些内容。