# 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.