Skip to content

Issue Tracking

Goal

Use GitHub Issues as the live roadmap and execution tracker. Use docs pages for concise product narrative and contributor guidance. Scribe can read, create, and update issues through GitHub CLI automation.

Contribution model

  • External contributions should start as issues with clear acceptance criteria.
  • Maintainer and Scribe open implementation pull requests for accepted work.
  • If external code already exists, attach a fork-branch link or coding-agent session link in the issue.
  • One issue per feature slice or bug.
  • Clear acceptance criteria in each issue.
  • Explicit labels for status, type, and area.

Live roadmap views

Keep docs and issues aligned

  • Product summary pages point to roadmap views.
  • Issue closures trigger doc updates where behavior changed.
  • Roadmap docs stay short and link to issue filters for current state.

GitHub CLI comment formatting

  • Use real multiline comment bodies for GitHub Issues.
  • Do not pass literal \n escape sequences in comment text.
  • Preferred close flow: post the completion comment first, then close the issue.
gh issue comment 123 --body-file - <<'EOF'
Closing as completed.

Implemented in commit abc1234.

Verified with targeted tests:
- swift test --filter ExampleTests
EOF

gh issue edit 123 --remove-label status/in-progress --add-label status/done
gh issue close 123 --reason completed
  • If a single close command is required, use command substitution with a heredoc so newlines are preserved.
gh issue close 123 --reason completed --comment "$(cat <<'EOF'
Closing as completed.

Implemented in commit abc1234.
EOF
)"

Continue