project-statement

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

project-statement

project-statement

Maintains
PROJECT_STATEMENT.yaml
(source of truth, gitignored) and renders it to
PROJECT_STATEMENT.md
(paste into a copy of the company-template Google Doc).
维护
PROJECT_STATEMENT.yaml
(唯一事实来源,已由 gitignore 忽略),并将其渲染为
PROJECT_STATEMENT.md
(粘贴到公司模板 Google Doc 的副本中)。

Operating principles

操作原则

  • One question at a time via
    AskUserQuestion
    — never batch.
  • Auto-detect first, ask second. Scan the repo before prompting.
  • Confirm detections with
    [Y/n/e]
    (and
    [a]
    for DVC: abandoned).
  • TODOs allowed everywhere — sentinel string
    "TODO: <reason>"
    , rendered inline with 🚧.
  • YAML is the source of truth. Updates = edit YAML by hand and re-run the skill to re-render. Never edit the rendered
    .md
    directly.
  • No fields outside SCHEMA.md. Don't invent ad-hoc keys.
  • 每次只问一个问题,通过
    AskUserQuestion
    进行——绝不批量提问。
  • 先自动检测,再进行询问。 在提示用户前扫描仓库。
  • 使用
    [Y/n/e]
    确认检测结果(对于 DVC,还可使用
    [a]
    表示 abandoned)。
  • 任何位置都允许 TODO——使用哨兵字符串
    "TODO: <reason>"
    ,渲染时在行内附带 🚧。
  • YAML 是唯一事实来源。 更新 = 手动编辑 YAML,然后重新运行该 skill 以重新渲染。切勿直接编辑已渲染的
    .md
    。
  • 不得添加 SCHEMA.md 之外的字段。 不要创建临时键。

Workflow

工作流

  1. Detect mode — check for
    PROJECT_STATEMENT.yaml
    in cwd:
    • 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.
  2. Scan repo for pre-fill data. See references/SCHEMA.md § "Pre-fill scan list". Build a detection summary.
  3. Confirm
    project_type
    — auto-detect from signals, present, confirm with single Y/n prompt. Defaults: notebooks + ML deps +
    .dvc/
    →
    data-science
    ; otherwise
    software
    .
  4. Confirm
    name
    — from README H1, else
    pyproject.toml
    /
    package.json
    name, else repo directory name.
  5. Interview — walk sections in this order:
    goal
    →
    definition_of_done
    →
    team
    →
    constraints
    →
    repositories
    →
    tools
    →
    folders
    →
    datasets
    (DS only) →
    experiment_log
    (DS only)
    For 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
      TODO:
      sentinel.
    • List sections support one-by-one entry. For
      team
      ,
      repositories
      ,
      tools
      ,
      folders
      , and
      datasets
      , 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.
    • 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
      TODO:
      sentinel describing the missing target instead of a vague phrase.
    • Tool picker (DS-related at end): Slack, GDrive, Jira, Confluence, NAS, Miro, MLFlow, DVC, CVAT, Label Studio, Other.
      url
      is optional
      — do NOT prompt for a Slack URL (record the entry with just an optional note); omit
      url
      for any tool with no useful link.
    • Datasets in DS projects is mandatory — must have ≥ 1 entry. A TODO entry counts.
  6. Validate — see references/SCHEMA.md § "Validation rules". On failure, re-prompt for the offending fields only.
  7. Write YAML to
    PROJECT_STATEMENT.yaml
    at project root.
  8. Ensure gitignore — append
    PROJECT_STATEMENT.*
    to
    .gitignore
    if not already present. Create
    .gitignore
    with that single line if it doesn't exist. Warn (do not skip) if
    .gitignore
    is tracked but read-only.
  9. Render — run
    python scripts/render.py PROJECT_STATEMENT.yaml > PROJECT_STATEMENT.md
    (use the skill's own scripts dir). The script needs
    PyYAML
    — most project Python envs already have it; if not, activate one that does (e.g., a conda env), or
    pip install pyyaml
    . Then print a short summary: total TODOs, where the file is, "paste into a copy of the company template Google Doc".
  1. 检测模式——检查 cwd 中是否存在
    PROJECT_STATEMENT.yaml
    :
    • 不存在 → 访谈模式(步骤 2–8)。
    • 存在且有效 → 渲染模式(仅执行步骤 9)。
    • 存在但缺少必填字段 → 仅针对缺失字段执行访谈,然后进行渲染。
  2. 扫描仓库以查找预填充数据。参阅
    references/SCHEMA.md
    中的“Pre-fill scan list”章节。生成检测结果摘要。
  3. 确认
    project_type
    ——根据相关信号自动检测,展示检测结果,并通过单个 Y/n 提示进行确认。默认值:notebooks + ML 依赖 +
    .dvc/
    →
    data-science
    ;其他情况 →
    software
    。
  4. 确认
    name
    ——优先取自 README H1,其次取自
    pyproject.toml
    /
    package.json
    的 name,最后使用仓库目录名。
  5. 访谈——按以下顺序逐节处理:
    goal
    →
    definition_of_done
    →
    team
    →
    constraints
    →
    repositories
    →
    tools
    →
    folders
    →
    datasets
    (仅 DS)→
    experiment_log
    (仅 DS)
    每个部分的操作如下:
    • 先显示检测到的条目;用户可用 Y 接受、n 拒绝、e 编辑。
    • 对于 DVC 工具检测,还应提供 a = abandoned(新增带有
      note: abandoned
      的条目)。
    • 检测完成后,继续询问是否需要手动添加条目,直到用户表示没有更多内容。
    • 每个提示都应提供“填写值 / 跳过 / TODO”——选择跳过时写入
      TODO:
      哨兵值。
    • 列表类字段支持逐项录入。 对于
      team
      、
      repositories
      、
      tools
      、
      folders
      和
      datasets
      ,完成检测后始终提供“再添加一项”路径:提出一个问题,其 Other 自由文本字段接受单个条目(例如一人:“姓名 — 角色 — YYYY-MM[ — YYYY-MM]”)。捕获该条目后,再次询问“再添加一项?”并循环,直到用户拒绝。不要要求用户一次输入完整名册/列表;即使用户这样做也可以接受,但默认方式是一次录入一项。
    • 不收集个人联系信息。 绝不收集或存储团队成员的电子邮件地址(或电话号码/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。
      url
      是可选项
      ——不要提示用户输入 Slack URL(该条目只记录可选备注);对于没有实用链接的工具,省略
      url
      。
    • DS 项目中的 datasets 为必填项——必须至少有 1 个条目。TODO 条目也计入。
  6. 验证——参阅
    references/SCHEMA.md
    中的“Validation rules”章节。验证失败时,仅重新提示有问题的字段。
  7. 将 YAML 写入项目根目录下的
    PROJECT_STATEMENT.yaml
    。
  8. 确保 gitignore 生效——如果尚未包含,则将
    PROJECT_STATEMENT.*
    追加到
    .gitignore
    。如果
    .gitignore
    不存在,则创建该文件并仅写入这一行。如果
    .gitignore
    已被 Git 跟踪但处于只读状态,则发出警告(不要跳过)。
  9. 渲染——运行
    python scripts/render.py PROJECT_STATEMENT.yaml > PROJECT_STATEMENT.md
    (使用该 skill 自身的 scripts 目录)。脚本需要
    PyYAML
    ——大多数项目 Python 环境已经安装;如果没有,请激活一个包含该依赖的环境(例如 conda 环境),或执行
    pip install pyyaml
    。然后打印简短摘要:TODO 总数、文件位置,以及“粘贴到公司模板 Google Doc 的副本中”这一提示。

Files written

写入的文件

  • PROJECT_STATEMENT.yaml
    — source of truth, gitignored.
  • PROJECT_STATEMENT.md
    — rendered output, gitignored. Paste this into the Google Doc.
  • .gitignore
    — appended if needed.
  • PROJECT_STATEMENT.yaml
    ——唯一事实来源,已由 gitignore 忽略。
  • PROJECT_STATEMENT.md
    ——渲染后的输出,已由 gitignore 忽略。将此文件粘贴到 Google Doc 中。
  • .gitignore
    ——如有需要则追加内容。

Anti-patterns

反模式

  • Inferring values silently — always show detections and confirm.
  • Batching multiple questions in one prompt.
  • Rendering without saving YAML first.
  • Editing the
    .md
    directly (it's a generated artifact and will be overwritten).
  • Adding fields not defined in SCHEMA.md.
  • Auto-pre-filling team members from
    CODEOWNERS
    /
    AUTHORS
    /
    pyproject.toml
    authors (signal is too stale; ask the user instead).
  • 静默推断值——始终展示检测结果并确认。
  • 在一次提示中批量提出多个问题。
  • 未先保存 YAML 就进行渲染。
  • 直接编辑
    .md
    (它是生成产物,会被覆盖)。
  • 添加 SCHEMA.md 中未定义的字段。
  • 根据
    CODEOWNERS
    /
    AUTHORS
    /
    pyproject.toml
    authors 自动预填团队成员(这些信号可能过于陈旧;应改为询问用户)。

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