go-guide

name

go-guide

description

Adds a new conceptual guide to a project's knowledge folder. Runs in three modes: interactive (user-invoked), from-task (auto-invoked from ship-first after a fast-track completes), from-epic (from epic closure). Storage: local `.md` file under `project-knowledge/guides/{topic}/`, registered via git commit + push. No database, no admin panel — the file itself is the artifact, discoverable via file tree or search. Flow: project selection → topic selection → title → text → .md creation → git push. Use when: "/go-guide", "add guide", "new guide", "save concept", or auto-invoked at the end of ship-first when work produced a reusable concept worth documenting.

/go-guide — Add a Conceptual Guide

Captures a durable concept — architectural decision, workflow rule, domain vocabulary — into the project's knowledge folder so future readers (including the same person in three months) can rediscover it without digging through commits.

---

Step 0 — Choose invocation mode

Three modes cover three lifecycles:

Mode	Trigger	Behavior
interactive	User types /go-guide	Full flow, asks project + topic + title + text
from-task	Skill('go-guide', mode='from-task', task_slug=…)	ship-first hook after fast-track close; suggests title/text from task context, user edits
from-epic	Skill('go-guide', mode='from-epic', epic_slug=…)	Epic closure hook; same as from-task but scoped to whole epic

---

Step 1 — Select project

Read aihub/projects.yml. Show numbered menu of projects. Wait for user choice or partial-name match.

Save to session context:

• {project_id} = chosen project id (slug)
• {project_path} = project's local path
• {knowledge_root} = {project_path}/project-knowledge/guides/

If {project_path} doesn't have project-knowledge/ folder — create it:

mkdir -p "{project_path}/project-knowledge/guides/"

---

Step 2 — Select topic

A topic is a stable folder grouping guides by subject (e.g. architecture, workflows, terminology, decisions). Ask the user which topic; offer existing topics first:

ls "{knowledge_root}" 2>/dev/null

Show numbered menu + 0. New topic. If user picks new — ask for slug (lowercase, hyphens). Create the folder:

mkdir -p "{knowledge_root}/{topic_slug}/"

---

Step 3 — Compose title

For interactive mode — ask user for one-line title.

For from-task / from-epic mode — propose a title derived from task/epic slug + brief. Show proposal, wait for user edit or approval.

Convert to filename slug:

"Why we chose SQLite over Postgres" → "why-sqlite-over-postgres.md"

---

Step 4 — Compose text

interactive — ask user for content. Accept multiline paste.

from-task / from-epic — propose content derived from the source material:

• Task's task.md intent + key decisions from decision-*.md files
• Report highlights ("What was notable" sections)
• Any note-*.md capturing the essence

Show the proposal for user edit before saving. Never save auto-generated content without user approval.

---

Step 5 — Write file

FILE="{knowledge_root}/{topic_slug}/{title_slug}.md"

cat > "$FILE" <<EOF
# {title}

**Date:** {date}
**Topic:** {topic_slug}
**Source:** {task_slug or epic_slug or "interactive"}

{text}
EOF

Print the resolved path to the user for confirmation.

---

Step 6 — Register via git

cd "{project_path}"
git add "project-knowledge/guides/{topic_slug}/{title_slug}.md"
git commit -m "guide: add {title} ({topic_slug})"
git push origin main  # or the project's default branch

If push fails (auth, network, protected branch) — report the error but leave the file in place. User can push manually later; the guide isn't lost.

---

Step 7 — Confirm

Print a one-line summary to the user:

✅ Guide saved: project-knowledge/guides/{topic_slug}/{title_slug}.md
   Committed: {short_sha}

For from-task / from-epic mode — return to caller (ship-first) with {success: true, path: "…"}.

---

Discovery

Consumers find guides through three paths:

1. File tree — project-knowledge/guides/{topic}/ grouped by subject
2. Search — grep across the folder for keywords
3. Cross-reference — task reports and decision docs cite guide paths

No database or admin panel required. The file tree is the index.

---

Rules

• One guide = one concept. Long docs → split.
• Title should read as a claim or question, not a category label
• Topic folders are stable — don't renumber, don't rename lightly
• Guides are additive: new decisions supersede old ones via new files, don't edit old guides to reflect new state
• Never save auto-generated content without user approval, even in from-task mode

---

Anti-patterns

❌ Editing old guides instead of adding new

The guide why-sqlite.md reflected a 2024 decision. In 2026 the project moves to Postgres. The agent edits the old file to "update" it — the historical context vanishes.

Rule: old guides stay as-is. New decisions create new guides. Optionally cross-link: new guide adds "supersedes: why-sqlite.md" line at top.

❌ Saving without user preview in from-task mode

ship-first invoked go-guide from-task; agent auto-generated content from task artifacts and pushed without showing the user. Result: malformed guide committed to git history.

Rule: always show proposal + wait for approval in from-task / from-epic mode. User can edit or reject.

❌ Missing git push step

Guide file created but never committed. Next agent invocation overwrites it thinking it's uncommitted junk.

Rule: Step 6 is mandatory in all three modes. If push fails — report it, don't retry silently, but leave the file.

❌ Guide as an open todo

Agent uses go-guide to save "what still needs doing" — a running todo list. The knowledge folder fills up with never-actioned items that decay into noise. Future readers can't tell durable concepts from stale plans.

Rule: guides are durable concepts (why we chose X, how the domain works, what a term means). Open work items belong in tasks/, not project-knowledge/guides/. If it starts with a verb and has no answer yet, it's a task, not a guide.

---

Related skills

• ship-first — invokes go-guide in from-task mode after a fast-track closes; the guide captures the durable concept from the just-completed work
• plan-first — precedes execution; a guide often derives from a plan-first decision worth preserving beyond the current task
• decision-first — decisions and guides are siblings: decisions record why a choice was made in context; guides record what the resulting concept is, standalone

---

Step 99 — Log invocation

Before exiting, log this skill invocation to routing.db:

sqlite3 {routing_db} \
  "INSERT INTO skill_invocations (task_id, block_num, skill_name, invoked_at)
   VALUES ('{slug}', '{N}', 'go-guide', datetime('now'))" 2>/dev/null || true

If {slug} / {N} unknown → hook writes empty; || true guards failure.