groove-groovebook-publish

Outcome

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

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

Learning file format

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

# <One-sentence summary>

## Context

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

## Learning

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

## Groove skill area

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

PR body format

## Summary
<one-sentence summary>

## Context
<what triggered this>

## Learning
<the insight>

## Groove skill area
`<skill-area>`

---
*Published via groove-groovebook-publish*

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