PRD policy: templates, gate, and org defaults - #1
koushik-databrain wants to merge 1 commit into
Conversation
Every feature and hotfix gets a PRD, approved before the PR is reviewed. Agreed by Rahul and Koushik, August 2026. Today nothing enforces this. I checked: 10 PRD-ish issues across frontend-mono and backend, none labelled, no issue template in any repo, and PRDs scattered across issue bodies, repo .md files, Google Docs and Slack threads. Two Slack reminders have not fixed it, because a rule people must remember is not a gate. What this adds: - Two org-default issue forms. PRD (full) for anything crossing a repo boundary, changing a contract, or needing a migration. PRD (lite), one page, for fixes and hotfix RCAs. Rahul asked for a shorter template; a single long one would get routed around. - A reusable PRD gate workflow. A PR merges only if it references an issue carrying both PRD and prd-approved, or if a maintainer applies prd-exempt. Reads the PR body, title and branch name for #123, owner/repo#123 and full issue URLs. Cross-repo lookups need the PRD_GATE_TOKEN secret. - A PR template whose second section is "Deviations from the PRD". - docs/PRD-POLICY.md and docs/PRD-TEMPLATE.md. The template is the skeleton both existing PRDs already use, written down for the first time. - setup/install-prd-gate.sh creates the labels and can open the caller PRs. It never deletes and never force-pushes. Nothing enforces until someone makes "PRD gate / prd" a required status check. Until then the gate reports and does not block. Claude-Session: https://claude.ai/code/session_01E2afbz3AS1tATwMc5iaNCu
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| pull_request: | ||
| types: [opened, edited, reopened, synchronize, labeled, unlabeled] |
There was a problem hiding this comment.
When the linked PRD gains or loses prd-approved after this workflow runs, no configured event reruns the gate because these triggers only observe activity on the pull request. The required check therefore remains failed after approval or remains successful after approval is revoked until unrelated PR activity occurs.
Prompt To Fix With AI
This is a comment left during a code review.
Path: setup/caller-workflow.yml
Line: 17-18
Comment:
**PRD approval leaves stale checks**
When the linked PRD gains or loses `prd-approved` after this workflow runs, no configured event reruns the gate because these triggers only observe activity on the pull request. The required check therefore remains failed after approval or remains successful after approval is revoked until unrelated PR activity occurs.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
| const res = await fetch( | ||
| `https://api.github.com/repos/${ref.owner}/${ref.repo}/issues/${ref.number}`, | ||
| { headers: { | ||
| Authorization: `Bearer ${crossToken}`, | ||
| Accept: 'application/vnd.github+json', | ||
| 'User-Agent': 'databrainhq-prd-gate', | ||
| } }, | ||
| ); |
There was a problem hiding this comment.
If the shared token can read an issue that is hidden from readers of the caller repository, a PR author can submit that unrestricted owner/repository reference and the gate publishes the issue title and URL in the caller's workflow output. Restrict lookups to repositories with a compatible visibility boundary or avoid emitting metadata obtained with the shared credential.
How this was verified: PR-controlled repository coordinates flow without an allowlist into the token-authenticated fetch, and the returned metadata is written to notices, summaries, and failure output.
Prompt To Fix With AI
This is a comment left during a code review.
Path: .github/workflows/prd-gate.yml
Line: 116-123
Comment:
**Token-backed issue metadata oracle**
If the shared token can read an issue that is hidden from readers of the caller repository, a PR author can submit that unrestricted owner/repository reference and the gate publishes the issue title and URL in the caller's workflow output. Restrict lookups to repositories with a compatible visibility boundary or avoid emitting metadata obtained with the shared credential.
**How this was verified:** PR-controlled repository coordinates flow without an allowlist into the token-authenticated fetch, and the returned metadata is written to notices, summaries, and failure output.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| check: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/github-script@v7 |
There was a problem hiding this comment.
actions/github-script@v7 resolves through a mutable tag while this step receives repository permissions and the cross-repository issue token. Pinning the action to a reviewed full commit SHA prevents an upstream tag change from executing different code with those credentials.
How this was verified: The executable action uses the mutable v7 tag and the same step receives CROSS_REPO_TOKEN through its environment.
Prompt To Fix With AI
This is a comment left during a code review.
Path: .github/workflows/prd-gate.yml
Line: 42
Comment:
**Mutable workflow action reference**
`actions/github-script@v7` resolves through a mutable tag while this step receives repository permissions and the cross-repository issue token. Pinning the action to a reviewed full commit SHA prevents an upstream tag change from executing different code with those credentials.
**How this was verified:** The executable action uses the mutable `v7` tag and the same step receives `CROSS_REPO_TOKEN` through its environment.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| git -C "$tmp/$repo" checkout -b chore/prd-gate | ||
| git -C "$tmp/$repo" add .github/workflows/prd-gate.yml | ||
| git -C "$tmp/$repo" commit -m "ci: require an approved PRD before a PR can merge" | ||
| git -C "$tmp/$repo" push -u origin chore/prd-gate | ||
| gh pr create --repo "$ORG/$repo" --base main --head chore/prd-gate \ |
There was a problem hiding this comment.
When --with-workflow is rerun after an earlier invocation created chore/prd-gate or its pull request, the fixed branch push or unconditional duplicate PR creation fails. Because set -e aborts a sequential multi-repository installation, later repositories remain unconfigured while changes made to earlier repositories persist.
Prompt To Fix With AI
This is a comment left during a code review.
Path: setup/install-prd-gate.sh
Line: 51-55
Comment:
**Installer cannot resume safely**
When `--with-workflow` is rerun after an earlier invocation created `chore/prd-gate` or its pull request, the fixed branch push or unconditional duplicate PR creation fails. Because `set -e` aborts a sequential multi-repository installation, later repositories remain unconfigured while changes made to earlier repositories persist.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.
1 participant
Makes the PRD policy Rahul and I agreed enforceable, instead of a reminder.
Why now
I checked the org before writing this:
frontend-monoandbackend. None carry a label..github,frontend-monoorbackend..mdfiles, Google Docs, Slack threads.Two Slack reminders have not changed that, because a rule people have to remember is
not a gate. This makes it a status check.
What is here
.github/ISSUE_TEMPLATE/prd.yml.github/ISSUE_TEMPLATE/prd-lite.yml.github/workflows/prd-gate.yml.github/PULL_REQUEST_TEMPLATE.mddocs/PRD-POLICY.mddocs/PRD-TEMPLATE.mdsetup/install-prd-gate.shTwo calls worth arguing about
1. Two template sizes, not one. The Semantic Layer PRD is ~8000 words. If a border
colour fix needs that, people route around the rule. The gate checks that a PRD
exists, not which size.
2. There is an escape hatch. A maintainer can put
prd-exempton a PR to skip thegate. It exists so this never blocks a real outage fix. Every use is visible in the PR
timeline.
This does not enforce anything yet
Three steps need an org admin, and I deliberately did not script them:
databrainhq/.github-> Settings -> Actions -> General -> Access -> allow org repos.PRD_GATE_TOKEN(read access to Issues) for cross-repo links.PRD gate / prda required status check on each repo's default branch.Until step 3, the gate reports and does not block. Merging this changes nothing on its
own, which is the point: you two decide when it starts biting.
Tested
shapes including
PRD: #3379,databrainhq/frontend-mono#7873, full issue URLs, anda dependabot body (correctly finds nothing).
install-prd-gate.shpassesbash -n. Not run — no labels created yet.Companion, not in this PR
Edith gets
/edith-prd <issue>(drafts a PRD into an issue, never approves it) and/edith-build <issue>(hands an approved PRD to a Cursor cloud agent, which branches,builds, and opens a PR). Written and tested, not deployed.
https://claude.ai/code/session_01E2afbz3AS1tATwMc5iaNCu
Greptile Summary
This PR introduces organization-wide PRD issue templates, policy documentation, a reusable approval gate, and an installer for rolling the gate out to selected repositories.
Confidence Score: 4/5
The approval-refresh defect should be fixed before enabling the gate as a required check; the cross-repository metadata boundary and workflow dependency pinning also need hardening.
The gate evaluates issue approval only on pull-request activity, so subsequent approval or revocation leaves the required check stale, while unrestricted token-backed issue reads and mutable action resolution add non-blocking security concerns.
Files Needing Attention: setup/caller-workflow.yml, .github/workflows/prd-gate.yml, setup/install-prd-gate.sh
Security Review
The cross-repository lookup accepts unrestricted repositories and emits token-readable issue metadata into caller workflow output, which can cross repository visibility boundaries. The workflow also references its executable action through a mutable version tag rather than an immutable commit.
Important Files Changed
Flowchart
%%{init: {'theme': 'neutral'}}%% flowchart TD A[Pull request event] --> B[Run reusable PRD gate] B --> C[Read linked issue labels] C -->|Approved| D[Successful required check] C -->|Not approved| E[Failed required check] F[PRD issue label changes] -. no caller trigger .-> B F --> G[Existing check remains stale]Prompt To Fix All With AI
Reviews (1): Last reviewed commit: "feat: PRD policy — templates, gate, and ..." | Re-trigger Greptile