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
repo
PR uses the groovebook PR template format (Summary, Context, Learning, Groove skill area)
File is written at
learned//-.md
in the groovebook repo
PR URL is printed to the user
Steps
Read
groovebook:
from
.groove/index.md
; if absent, exit with:
groovebook is not configured. Add 'groovebook: /' to .groove/index.md to enable.
Check
gh auth status
; if not authenticated, exit with:
Not authenticated with GitHub. Run: gh auth login
Verify the groovebook repo is accessible:
gh repo view
; if it fails, exit with a clear message.
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)
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
Ask for topic (e.g.
patterns
,
tools
,
anti-patterns
,
workflow
) and skill area (e.g.
compound
,
plan
,
review
,
daily
)
Generate slug: lowercase the summary, replace spaces with hyphens, strip special characters, truncate to 40 chars. Construct:
Branch name:
learning/-
File path:
learned//-.md
Fork the groovebook repo if not already forked:
gh repo fork --clone=false
If fork already exists, skip silently
Create the branch and file:
gh api repos//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
Open the PR:
gh pr create --repo \
--title "" \
--body "" \
--head ":"
Print the PR URL
Learning file format
date
:
YYYY
-
MM
-
DD
topic
:
<topic
skill-area
:
<skill
-
area
source
:
groovebook
-
publish
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
Context
Learning
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