project-statement
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineseproject-statement
project-statement
Maintains (source of truth, gitignored) and renders it to (paste into a copy of the company-template Google Doc).
PROJECT_STATEMENT.yamlPROJECT_STATEMENT.md维护 (唯一事实来源,已由 gitignore 忽略),并将其渲染为 (粘贴到公司模板 Google Doc 的副本中)。
PROJECT_STATEMENT.yamlPROJECT_STATEMENT.mdOperating principles
操作原则
- One question at a time via — never batch.
AskUserQuestion - Auto-detect first, ask second. Scan the repo before prompting.
- Confirm detections with (and
[Y/n/e]for DVC: abandoned).[a] - TODOs allowed everywhere — sentinel string , rendered inline with 🚧.
"TODO: <reason>" - YAML is the source of truth. Updates = edit YAML by hand and re-run the skill to re-render. Never edit the rendered directly.
.md - No fields outside SCHEMA.md. Don't invent ad-hoc keys.
- 每次只问一个问题,通过 进行——绝不批量提问。
AskUserQuestion - 先自动检测,再进行询问。 在提示用户前扫描仓库。
- 使用 确认检测结果(对于 DVC,还可使用
[Y/n/e]表示 abandoned)。[a] - 任何位置都允许 TODO——使用哨兵字符串 ,渲染时在行内附带 🚧。
"TODO: <reason>" - YAML 是唯一事实来源。 更新 = 手动编辑 YAML,然后重新运行该 skill 以重新渲染。切勿直接编辑已渲染的 。
.md - 不得添加 SCHEMA.md 之外的字段。 不要创建临时键。
Workflow
工作流
-
Detect mode — check forin cwd:
PROJECT_STATEMENT.yaml- Missing → interview mode (steps 2–8).
- Present, valid → render mode (step 9 only).
- Present, missing required fields → run interview only for missing fields, then render.
-
Scan repo for pre-fill data. See references/SCHEMA.md § "Pre-fill scan list". Build a detection summary.
-
Confirm— auto-detect from signals, present, confirm with single Y/n prompt. Defaults: notebooks + ML deps +
project_type→.dvc/; otherwisedata-science.software -
Confirm— from README H1, else
name/pyproject.tomlname, else repo directory name.package.json -
Interview — walk sections in this order:→
goal→definition_of_done→team→constraints→repositories→tools→folders(DS only) →datasets(DS only)experiment_logFor each section:- Show detected items first; user accepts with Y, rejects with n, edits with e.
- For DVC tool detection, also offer a = abandoned (adds entry with ).
note: abandoned - After detections, ask for additional manual entries until user says no more.
- For every prompt offer "value / skip / TODO" — skip writes a sentinel.
TODO: - List sections support one-by-one entry. For ,
team,repositories,tools, andfolders, after the detections always offer an "add one more" path: a question whose Other free-text field accepts a single entry (e.g. one person: "Name — Role — YYYY-MM[ — YYYY-MM]"). Capture it, then re-ask "add another?" and loop until the user declines. Don't force the user to type the whole roster/list as one blob — accept it if they do, but the default offer is one entry at a time.datasets - No personal contact details. Never collect or store email addresses (or phone/handles) for team members. Name, role, and join/leave months only.
- Role picker uses the fixed list: Tech Lead, Project Manager, Data Scientist, Software Developer, Annotator, Full Stack Engineer, Frontend Developer, Tester, Other. DS-related roles last for software projects; software-related roles last for DS projects.
- Constraints must be concrete and measurable. Ask for the actual number/threshold and what it applies to — e.g. "latency: <100ms per model on iPhone 15 Pro", "detection mAP ≥ 0.90", "model size < 50MB" — not vague adjectives like "low latency" or "high accuracy". If the user has no number yet, write a sentinel describing the missing target instead of a vague phrase.
TODO: - Tool picker (DS-related at end): Slack, GDrive, Jira, Confluence, NAS, Miro, MLFlow, DVC, CVAT, Label Studio, Other. is optional — do NOT prompt for a Slack URL (record the entry with just an optional note); omit
urlfor any tool with no useful link.url - Datasets in DS projects is mandatory — must have ≥ 1 entry. A TODO entry counts.
-
Validate — see references/SCHEMA.md § "Validation rules". On failure, re-prompt for the offending fields only.
-
Write YAML toat project root.
PROJECT_STATEMENT.yaml -
Ensure gitignore — appendto
PROJECT_STATEMENT.*if not already present. Create.gitignorewith that single line if it doesn't exist. Warn (do not skip) if.gitignoreis tracked but read-only..gitignore -
Render — run(use the skill's own scripts dir). The script needs
python scripts/render.py PROJECT_STATEMENT.yaml > PROJECT_STATEMENT.md— most project Python envs already have it; if not, activate one that does (e.g., a conda env), orPyYAML. Then print a short summary: total TODOs, where the file is, "paste into a copy of the company template Google Doc".pip install pyyaml
-
检测模式——检查 cwd 中是否存在:
PROJECT_STATEMENT.yaml- 不存在 → 访谈模式(步骤 2–8)。
- 存在且有效 → 渲染模式(仅执行步骤 9)。
- 存在但缺少必填字段 → 仅针对缺失字段执行访谈,然后进行渲染。
-
扫描仓库以查找预填充数据。参阅中的“Pre-fill scan list”章节。生成检测结果摘要。
references/SCHEMA.md -
确认——根据相关信号自动检测,展示检测结果,并通过单个 Y/n 提示进行确认。默认值:notebooks + ML 依赖 +
project_type→.dvc/;其他情况 →data-science。software -
确认——优先取自 README H1,其次取自
name/pyproject.toml的 name,最后使用仓库目录名。package.json -
访谈——按以下顺序逐节处理:→
goal→definition_of_done→team→constraints→repositories→tools→folders(仅 DS)→datasets(仅 DS)experiment_log每个部分的操作如下:- 先显示检测到的条目;用户可用 Y 接受、n 拒绝、e 编辑。
- 对于 DVC 工具检测,还应提供 a = abandoned(新增带有 的条目)。
note: abandoned - 检测完成后,继续询问是否需要手动添加条目,直到用户表示没有更多内容。
- 每个提示都应提供“填写值 / 跳过 / TODO”——选择跳过时写入 哨兵值。
TODO: - 列表类字段支持逐项录入。 对于 、
team、repositories、tools和folders,完成检测后始终提供“再添加一项”路径:提出一个问题,其 Other 自由文本字段接受单个条目(例如一人:“姓名 — 角色 — YYYY-MM[ — YYYY-MM]”)。捕获该条目后,再次询问“再添加一项?”并循环,直到用户拒绝。不要要求用户一次输入完整名册/列表;即使用户这样做也可以接受,但默认方式是一次录入一项。datasets - 不收集个人联系信息。 绝不收集或存储团队成员的电子邮件地址(或电话号码/handle)。仅收集姓名、角色和加入/离职月份。
- 角色选择器使用固定列表:Tech Lead、Project Manager、Data Scientist、Software Developer、Annotator、Full Stack Engineer、Frontend Developer、Tester、Other。对于软件项目,与 DS 相关的角色排在最后;对于 DS 项目,与软件相关的角色排在最后。
- 约束必须具体且可衡量。 询问实际数值/阈值及其适用对象,例如“latency: <100ms per model on iPhone 15 Pro”“detection mAP ≥ 0.90”“model size < 50MB”,而不是“低延迟”或“高准确度”之类的模糊形容词。如果用户尚无具体数值,则写入描述缺失目标的 哨兵值,而不是使用模糊表述。
TODO: - 工具选择器(与 DS 相关的工具排在末尾):Slack、GDrive、Jira、Confluence、NAS、Miro、MLFlow、DVC、CVAT、Label Studio、Other。是可选项——不要提示用户输入 Slack URL(该条目只记录可选备注);对于没有实用链接的工具,省略
url。url - DS 项目中的 datasets 为必填项——必须至少有 1 个条目。TODO 条目也计入。
-
验证——参阅中的“Validation rules”章节。验证失败时,仅重新提示有问题的字段。
references/SCHEMA.md -
将 YAML 写入项目根目录下的。
PROJECT_STATEMENT.yaml -
确保 gitignore 生效——如果尚未包含,则将追加到
PROJECT_STATEMENT.*。如果.gitignore不存在,则创建该文件并仅写入这一行。如果.gitignore已被 Git 跟踪但处于只读状态,则发出警告(不要跳过)。.gitignore -
渲染——运行(使用该 skill 自身的 scripts 目录)。脚本需要
python scripts/render.py PROJECT_STATEMENT.yaml > PROJECT_STATEMENT.md——大多数项目 Python 环境已经安装;如果没有,请激活一个包含该依赖的环境(例如 conda 环境),或执行PyYAML。然后打印简短摘要:TODO 总数、文件位置,以及“粘贴到公司模板 Google Doc 的副本中”这一提示。pip install pyyaml
Files written
写入的文件
- — source of truth, gitignored.
PROJECT_STATEMENT.yaml - — rendered output, gitignored. Paste this into the Google Doc.
PROJECT_STATEMENT.md - — appended if needed.
.gitignore
- ——唯一事实来源,已由 gitignore 忽略。
PROJECT_STATEMENT.yaml - ——渲染后的输出,已由 gitignore 忽略。将此文件粘贴到 Google Doc 中。
PROJECT_STATEMENT.md - ——如有需要则追加内容。
.gitignore
Anti-patterns
反模式
- Inferring values silently — always show detections and confirm.
- Batching multiple questions in one prompt.
- Rendering without saving YAML first.
- Editing the directly (it's a generated artifact and will be overwritten).
.md - Adding fields not defined in SCHEMA.md.
- Auto-pre-filling team members from /
CODEOWNERS/AUTHORSauthors (signal is too stale; ask the user instead).pyproject.toml
- 静默推断值——始终展示检测结果并确认。
- 在一次提示中批量提出多个问题。
- 未先保存 YAML 就进行渲染。
- 直接编辑 (它是生成产物,会被覆盖)。
.md - 添加 SCHEMA.md 中未定义的字段。
- 根据 /
CODEOWNERS/AUTHORSauthors 自动预填团队成员(这些信号可能过于陈旧;应改为询问用户)。pyproject.toml
References
参考资料
- Full schema, enums, scan list, validation rules, icon registry → SCHEMA.md
- Worked example with filled YAML + rendered MD → EXAMPLE.md
- Deterministic renderer → scripts/render.py
- 完整 schema、枚举、扫描列表、验证规则和图标注册表 → SCHEMA.md
- 包含已填写 YAML 和已渲染 MD 的完整示例 → EXAMPLE.md
- 确定性渲染器 → scripts/render.py