GitHub Tactics

Status: WORKING INTERNAL TACTICS
Date: 2026-05-09
Depends on: docs/GITHUB_STRATEGY.md
Not for publication: internal operating document

1. Tactical objective

Turn the repository into a high-trust PostgreSQL extension project in three passes:

  1. coherence
  2. governance
  3. proof

2. Non-negotiable operating rules

R1. No public release without version coherence

Before any GitHub release is marked latest, these must match: - release tag - release title - README version badge - CHANGELOG.md - META.json - extension/pgmnemo.control - version strings in install and usage docs

R2. No public API example may target an unshipped contract

README and docs must only show the SQL/API surface already shipped in the latest published release.

R3. CI must communicate real confidence

Non-blocking CI steps are allowed only if clearly labeled temporary and tracked to removal. Primary install path and CREATE EXTENSION path must become hard-green before the next maturity push.

R4. Each doc page must have one job

  • README = understand + start
  • INSTALL = install + upgrade
  • USAGE = exact contract
  • MIGRATION = adopt from another system
  • benchmarks = validate claims

R5. Strategy docs cannot outrun shipped reality

If roadmap language still uses obsolete forms (install.sql, mem.*, pre-extension wedge-only framing), revise or archive it.

R6. Every important claim needs a proof object

  • faster -> benchmark artifact
  • trusted -> provenance gate description + enforcement semantics
  • portable -> tested version matrix
  • maintained -> issues/templates/releases cadence

R7. GitHub issues are part of the product

Visible issues and milestones are a trust signal, not a shame signal.

R8. Benchmarks are first-class repo assets

Benchmarks should expose: - dataset description - reproduction command - metrics definition - protocol change log

3. Owner matrix

Area Primary owner Required reviewer
README / positioning / docs map Growth Lead Technical Lead
INSTALL / upgrade path Technical Lead Chief Architect
USAGE / API truth Technical Lead Chief Architect
release notes / latest-tag hygiene Technical Lead Growth Lead
issue templates / community flow Growth Lead Technical Lead
benchmarks / methodology pages Technical Lead Experiment Designer
public roadmap and milestones Growth Lead Startup Mentor
competitor comparison pages Growth Lead Competitive Intelligence

4. Immediate hardening backlog

Batch A — Release coherence

A1. Synchronize published version surface

  • latest GitHub release matches current intended public version
  • README badge matches latest release
  • release notes summarize actual shipped delta

A2. Add release checklist

Before tagging: - version strings synchronized - changelog complete - docs examples tested - install path tested - upgrade path tested - benchmark claim links present

A3. Make release notes operator-facing

Each release should state: - what changed - who should upgrade - upgrade command - incompatible changes - known caveats

Batch B — Governance and contribution surface

B1. Add .github/ISSUE_TEMPLATE/

Minimum templates: - bug report - install / upgrade issue - docs issue - benchmark discrepancy - feature request

B2. Add PR template

Require contributors to specify: - user-visible change - docs impact - benchmark impact - upgrade impact - release note needed or not

B3. Add CODE_OF_CONDUCT.md

B4. Add SECURITY.md

Must state: - how to report privately - supported versions - response expectations

B5. Add CODEOWNERS

Protect technical truth and release hygiene paths.

B6. Publish label system

Minimum labels: - bug - install - docs - benchmark - release-hygiene - good first issue - needs-repro - breaking-change - question

B7. Decide on Discussions

Open GitHub Discussions only if the team can answer consistently.

Batch C — Trust and proof surface

C1. Make benchmarks visible

Expose: - datasets - metrics - current results - rerun steps

C2. Promote migration guidance

MIGRATION.md should be first-class because migration is one of our adoption wedges.

C3. Add examples directory narrative

Examples should be named by user job: - quickstart - migration from external memory - hybrid recall - graph traversal

C4. Distinguish stable vs experimental features

Use one visible convention: - stable - experimental - planned

C5. Add compatibility matrix

Publish: - PostgreSQL versions - pgvector versions - OS/build assumptions - install paths tested - upgrade paths tested

C6. Add production-readiness page

Must answer: - what beta means - what is tested - what is not yet guaranteed - what production adopters must verify themselves

5. Public docs target map

  • README.md
  • INSTALL.md
  • docs/USAGE.md
  • docs/MIGRATION.md
  • docs/COMPATIBILITY.md
  • docs/PRODUCTION_READINESS.md
  • docs/BENCHMARKS.md
  • docs/ROADMAP.md
  • CONTRIBUTING.md
  • SECURITY.md
  • CODE_OF_CONDUCT.md

6. Weekly operating cadence

Monday — repo hygiene review

Owner: TL + Growth Lead

Check: - latest release coherence - open issue triage - docs drift - README / INSTALL / USAGE mismatches

Wednesday — proof review

Owner: TL

Check: - benchmark artifacts current - CI meaningfully green - examples still runnable

Friday — external signal review

Owner: Growth Lead

Check: - competitor moves - new star / issue / contributor signals - pages confusing new visitors

Every 2 weeks — brutal critique review

Owner: Startup Mentor

Question: - would a skeptical maintainer trust this repo more than last review?

7. Definition of GitHub maturity

The repo can be called technically mature on GitHub when:

  1. latest release, docs, and version files never drift for more than 24 hours
  2. install + upgrade paths are explicitly documented and tested
  3. issue templates and PR template exist and are used
  4. benchmark claims point to reproducible artifacts
  5. strategy and roadmap language no longer contain obsolete pre-extension framing
  6. a new user can identify the stable API surface without reading internal planning docs

8. 30-day tactical sequence

Week 1

  • close version drift
  • clean README / USAGE / INSTALL contract
  • tag one coherent release

Week 2

  • add issue templates, PR template, SECURITY.md, CODE_OF_CONDUCT.md, CODEOWNERS
  • publish labels and triage rules
  • decide on Discussions and support policy

Week 3

  • publish benchmark and migration doc surfaces
  • classify stable vs experimental feature set
  • publish compatibility matrix and production-readiness page

Week 4

  • review public roadmap
  • remove obsolete internal-first GitHub language
  • run startup-mentor critique pass
  • clean root information architecture so users do not trip over internal-looking artifacts first

9. Red flags

  • latest release tag lags internal public docs
  • README examples do not match shipped API
  • benchmark claims cannot be reproduced
  • docs refer to deprecated naming surfaces
  • repo looks active internally but empty publicly
  • root directory looks like a maintainer workspace rather than a clean extension product
  • roadmap prose is used to hide install or upgrade ambiguity

10. Tactical decision

The next GitHub hardening cycle should prioritize:

  1. release coherence
  2. operator trust
  3. maintainer governance
  4. benchmark proof
  5. category-shaping clarity

Not more features, unless those features directly strengthen one of the five.