groove-groovebook-publish

groove-groovebook-publish

Use $ARGUMENTS as the learning text if provided.

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.

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