Skip to main content

Contribute

Feedback is managed in GitHub Issues so decisions stay public, reviewable, and traceable. Code and content changes should move through the strict branch and pull-request workflow.

Suggest an improvement​

  1. Open an issue: New issue
  2. Use a clear title with the affected rule, doc page, blog post, or workflow concept.
  3. Link the specific page and section.
  4. Describe the current problem, the expected improvement, and why it matters.
  5. If relevant, include a concrete wording proposal.

Branching and pull requests​

  1. Start from a GitHub issue or clearly linked governed task.
  2. Create an issue-scoped feature/, fix/, docs/, or chore/ branch from develop.
  3. Do not create a new normal work branch from another working branch; non-main / non-develop branches are work units, not parent branches.
  4. Do not let agents commit directly to main or develop.
  5. Move the governing issue to the correct project-board state as work advances (Ready before start, In progress during active work, In review once the PR is open, Done after merge/verification, or Blocked with evidence when stalled).
  6. Open a pull request into develop and complete the repo pull-request template with issue/spec/evidence links.
  7. Keep validation evidence in the pull request so promotion reviewers can reuse it.

Use the Branch Protection Checklist when setting up or reviewing repo protections.

Promotion and hotfix path​

  • Promote reviewed work from develop to main with an explicit pull request.
  • Start urgent fixes from main with hotfix/<issue>-<slug> branches.
  • After a hotfix lands in main, back-merge or otherwise reconcile it into develop immediately.
  • Record promotion scope, hotfix reason, and any back-merge reference in the related pull request.

Bootstrap adoption feedback​

If you have just run a fresh bootstrap or an update/remediation pass, use the Bootstrap Feedback Prompt.

Expected feedback flow:

  1. write scrubbed feedback to .governance/project/bootstrap/history/<timestamp>/feedback.md
  2. refresh .governance/project/bootstrap/FEEDBACK.md as the current reporting surface
  3. then raise a GitHub issue with the scrubbed result (or auto-file when requested)

Before posting, remove or obfuscate PII, secrets, tokens, emails, usernames, IDs, URLs, and environment-specific sensitive details.

That feedback is especially useful when it captures:

  • what was underspecified or ambiguous
  • what files should have been created earlier
  • what GitHub scopes or permissions were missing
  • what branch / board / PR behavior was unclear
  • what exact wording would have made bootstrap smoother

Strong contribution targets​

Especially useful contributions include:

  • unclear execution-mode boundaries
  • weak completion criteria
  • missing or weak evidence expectations
  • weak branch-protection or pull-request workflow guidance
  • blocker-handling ambiguity
  • exploratory-review loopholes
  • persistence-proof gaps
  • weak checkpoint/report examples
  • workflow wording that is easy to game or misread

Preferred issue types​

Contribution principles​

  • Preserve intent over surface wording.
  • Keep governance reusable across projects and providers.
  • Avoid project-specific tool lock-in in core rules.
  • Use issue-scoped branches and pull requests rather than bypassing protected branches.
  • Prefer guidance that is hard to misread and hard to execute badly.
  • If a rule sounds good but is easy to game, keep improving it.