git_workflow

Purpose

Standardize how we create and synchronize GitHub issues with Knowledge Graph Task:* entities. Prevent duplicates, ensure reliable shell behavior, and maintain a single canonical link per task.

Prerequisites

• Authenticated GitHub CLI: gh auth status
• Derive repo slug dynamically (never hardcode):
  • gh repo view --json nameWithOwner -q .nameWithOwner
• If no default repo is set and a command errors, set it:
  • gh repo set-default <owner/repo>

Canonical Workflow

1. Discover repository slug

   • SLUG=$(gh repo view --json nameWithOwner -q .nameWithOwner)

2. De-dup BEFORE creating issues

   • Search by normalized title/label. If a matching issue exists, DO NOT create a new one; log the URL and continue.
   • Examples:
     • gh issue list --repo "$SLUG" --search 'in:title "<normalized-title>"' --json number,title,url

3. Create issues using here-doc files (-F)

   • Always write the body to a file and use -F to avoid quoting problems.
   • Example:

     cat > /tmp/issue.md <<'EOF'
     Context: <why>
     Acceptance criteria:
     - item 1
     - item 2
     EOF
     gh issue create --repo "$SLUG" -t "P0: <Title> — <short>" -F /tmp/issue.md -l enhancement
     

4. Knowledge Graph sync (exactly one link)

   • For each Task:*, write back a single observation: GitHub: <url>
   • If a link already exists, UPDATE/REPLACE it; do not append a second link.
   • Link Task:* to Repo:* via relation tracks.
   • Ensure that KG & GH are updated IMMEDIATELY AFTER EVERY TASK COMPLETION, consider this step the last step of every task given.

5. On mistakes (duplicates)

   • Close duplicates rather than deleting the issue.
   • Re-sync KG: remove stale GitHub link observations so only the canonical link remains.

Mapping & Naming

• Maintain stable ordering: map core tasks to issues #1–#N. Add new tasks incrementally (e.g., new P0 becomes next number).
• Titles: P{0|1|2}: <TaskName> — <short description>
• Labels: bug for defects; enhancement for task/feature work.