Back to Details

groove-groovebook-publish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

groove-groovebook-publish

groove-groovebook-publish

Use $ARGUMENTS as the learning text if provided.
如果提供了$ARGUMENTS，则将其用作经验文本。

Outcome

输出结果

A learning from the current project is published to the configured groovebook repo as a pull request, stripped of any project-specific context, ready for community review.
当前项目的经验会以拉取请求的形式发布到已配置的groovebook仓库，所有项目专属上下文都会被移除，可供社区评审。

Acceptance Criteria

验收标准

  • Learning is published as a PR to 
    <groovebook>
    repo
  • PR uses the groovebook PR template format (Summary, Context, Learning, Groove skill area)
  • File is written at 
    learned/<topic>/<YYYY-MM-DD>-<slug>.md
    in the groovebook repo
  • PR URL is printed to the user
  • 经验作为PR发布到
    <groovebook>
    仓库
  • PR遵循groovebook PR模板格式（摘要、上下文、经验、Groove技能领域）
  • 文件写入groovebook仓库的
    learned/<topic>/<YYYY-MM-DD>-<slug>.md
    路径下
  • 向用户打印输出PR URL

Steps

操作步骤

  1. Read 
    groovebook:
    from 
    .groove/index.md
    ; if absent, exit with: 
    groovebook is not configured. Add 'groovebook: <owner>/<repo>' to .groove/index.md to enable.
  2. Check 
    gh auth status
    ; if not authenticated, exit with: 
    Not authenticated with GitHub. Run: gh auth login
  3. Verify the groovebook repo is accessible: 
    gh repo view <groovebook>
    ; if it fails, exit with a clear message.
  4. Get the learning text:
    • If $ARGUMENTS is provided, use it as a starting point
    • Otherwise: ask "What's the learning you'd like to publish? (paste it or describe briefly)"
    • Ask for a one-sentence summary (used as PR title and filename slug)
  5. Show a preview of the learning text and ask: 
    Does this contain any repo-specific context to redact? (file paths, internal names, product names)
    • If yes: help the user redact it — replace specific names with generic descriptions
    • If no: proceed
  6. Ask for topic (e.g. 
    patterns
    , 
    tools
    , 
    anti-patterns
    , 
    workflow
    ) and skill area (e.g. 
    compound
    , 
    plan
    , 
    review
    , 
    daily
    )
  7. Generate slug: lowercase the summary, replace spaces with hyphens, strip special characters, truncate to 40 chars. Construct:
    • Branch name: 
      learning/<YYYY-MM-DD>-<slug>
    • File path: 
      learned/<topic>/<YYYY-MM-DD>-<slug>.md
  8. Fork the groovebook repo if not already forked: 
    gh repo fork <groovebook> --clone=false
    • If fork already exists, skip silently
  9. Create the branch and file:
    • gh api repos/<user-fork>/git/refs
      to check if branch exists; if so, append a short unique suffix
    • Write the file content (see format below) and commit via 
      gh api
    • Or: use 
      git
      operations against the fork URL if 
      gh api
      approach is too complex — prefer the simpler path
  10. Open the PR:
    gh pr create --repo <groovebook> \
  --title "<one-sentence summary>" \
  --body "<formatted body>" \
  --head "<fork-user>:<branch-name>"
  11. Print the PR URL
  1. 读取
    .groove/index.md
    中的
    groovebook:
    配置；如果不存在，退出并提示： 
    groovebook is not configured. Add 'groovebook: <owner>/<repo>' to .groove/index.md to enable.
  2. 检查
    gh auth status
    ；如果未认证，退出并提示： 
    Not authenticated with GitHub. Run: gh auth login
  3. 验证groovebook仓库可访问：
    gh repo view <groovebook>
    ；如果失败，输出清晰的错误提示后退出。
  4. 获取经验文本：
    • 如果提供了$ARGUMENTS，将其作为初始内容
    • 否则询问用户："你想要发布的经验是什么？（可以粘贴内容或者简要描述）"
    • 向用户索要一句话摘要（用作PR标题和文件名slug）
  5. 预览经验文本并询问用户： 
    这份内容里有没有需要脱敏的仓库专属上下文？（比如文件路径、内部名称、产品名称）
    • 如果有：协助用户完成脱敏，将特定名称替换为通用描述
    • 如果没有：继续后续步骤
  6. 询问用户主题（例如
    patterns
    、
    tools
    、
    anti-patterns
    、
    workflow
    ）和技能领域（例如
    compound
    、
    plan
    、
    review
    、
    daily
    ）
  7. 生成slug：将摘要转为小写，空格替换为连字符，移除特殊字符，截断到40个字符。构造：
    • 分支名：
      learning/<YYYY-MM-DD>-<slug>
    • 文件路径：
      learned/<topic>/<YYYY-MM-DD>-<slug>.md
  8. 如果还未fork groobook仓库则执行fork操作：
    gh repo fork <groovebook> --clone=false
    • 如果已经fork过，静默跳过该步骤
  9. 创建分支和文件：
    • 调用
      gh api repos/<user-fork>/git/refs
      检查分支是否存在；如果存在，追加一个简短的唯一后缀
    • 写入文件内容（参考下方格式）并通过
      gh api
      提交
    • 或者：如果
      gh api
      方式太复杂，可以针对fork仓库URL执行
      git
      操作，优先选择更简单的实现方式
  10. 提交PR：
    gh pr create --repo <groovebook> \
  --title "<one-sentence summary>" \
  --body "<formatted body>" \
  --head "<fork-user>:<branch-name>"
  11. 打印输出PR URL

Learning file format

经验文件格式

markdown
---
date: YYYY-MM-DD
topic: <topic>
skill-area: <skill-area>
source: groovebook-publish
---
markdown
---
date: YYYY-MM-DD
topic: <topic>
skill-area: <skill-area>
source: groovebook-publish
---

<One-sentence summary>

<One-sentence summary>

Context

Context

<What triggered this learning — what problem were you solving? Generic, no project specifics.>
<What triggered this learning — what problem were you solving? Generic, no project specifics.>

Learning

Learning

<The insight itself — what to do, what to avoid, or what pattern works.>
<The insight itself — what to do, what to avoid, or what pattern works.>

Groove skill area

Groove skill area

<skill-area>
(e.g. 
groove-work-compound
, 
groove-work-plan
)
undefined
<skill-area>
(e.g. 
groove-work-compound
, 
groove-work-plan
)
undefined

PR body format

PR正文格式

undefined
undefined

Summary

Summary

<one-sentence summary>
<one-sentence summary>

Context

Context

<what triggered this>
<what triggered this>

Learning

Learning

<the insight>
<the insight>

Groove skill area

Groove skill area

<skill-area>
Published via groove-groovebook-publish
undefined
<skill-area>
Published via groove-groovebook-publish
undefined

Constraints

约束条件

  • Never publish learning text that contains project-specific names, file paths, or internal identifiers without explicit user confirmation that it's intentional
  • If the fork step fails due to permissions: suggest the user fork manually and set their fork as the 
    groovebook:
    value
  • Slug must be safe for use as a filename: lowercase, hyphens only, no path separators or special characters
  • If branch already exists: append 
    -2
    , 
    -3
    , etc. until a free name is found
  • 没有用户明确确认是故意发布的情况下，绝对不能发布包含项目专属名称、文件路径或内部标识符的经验文本
  • 如果fork步骤因权限失败：建议用户手动fork仓库，并将他们的fork仓库地址设置为
    groovebook:
    的配置值
  • Slug必须符合文件名安全规范：仅小写、仅使用连字符、无路径分隔符或特殊字符
  • 如果分支已存在：追加
    -2
    、
    -3
    等后缀直到找到可用的名称