Skip to content

Commit 106ff72

Browse files
DevanshuNEUDevanshuNEU
authored
Merge pull request #302 from DevanshuNEU/chore/oci-pipeline-templates-and-per-folder-claude
chore: per-folder CLAUDE.md, OCI PR template, OCI issue forms
2 parents 4e65fd8 + cb05f2e commit 106ff72

7 files changed

Lines changed: 619 additions & 29 deletions

File tree

‎.github/ISSUE_TEMPLATE/ddia-finding.yml‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
name: DDIA Finding
2+
description: An OCI flaw spotted while reading Designing Data-Intensive Applications. Routes reading-time insight into shipped improvements.
3+
title: "[ddia Ch _] "
4+
labels: ["ddia-finding", "state/backlog"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Closes the loop between DDIA reading and OCI improvements. Different shape from `dogfood-finding`:
10+
- `dogfood-finding` = "I used OCI's tools and they failed me"
11+
- `ddia-finding` = "I read DDIA and realized OCI does X wrong"
12+
13+
Be precise. Recruiters reading these issues should see clean DDIA fluency.
14+
15+
- type: input
16+
id: chapter
17+
attributes:
18+
label: DDIA chapter
19+
description: Which chapter triggered this. Update the title prefix to match (e.g. `[ddia Ch 5]`).
20+
placeholder: "Ch 5 - Replication"
21+
validations:
22+
required: true
23+
24+
- type: input
25+
id: concept
26+
attributes:
27+
label: Specific concept
28+
description: Which section or term inside that chapter. Be precise.
29+
placeholder: "Read-after-write consistency under async replication"
30+
validations:
31+
required: true
32+
33+
- type: input
34+
id: surface
35+
attributes:
36+
label: OCI surface affected
37+
description: Which file, service, or design decision is wrong. Absolute path from repo root preferred.
38+
placeholder: "backend/services/search.py, Pinecone upsert path"
39+
validations:
40+
required: true
41+
42+
- type: checkboxes
43+
id: stack
44+
attributes:
45+
label: Stack
46+
options:
47+
- label: backend
48+
- label: frontend
49+
- label: mcp-server
50+
- label: cross-cutting
51+
52+
- type: textarea
53+
id: whats-wrong
54+
attributes:
55+
label: What is wrong (DDIA-grounded)
56+
description: 2-4 sentences. Lead with the DDIA principle, then how OCI violates it. No vibes.
57+
placeholder: |
58+
DDIA Ch 5 argues that asynchronous replication breaks read-after-write within a session unless reads are pinned to the leader for a brief window. OCI's search endpoint writes to Pinecone (async upsert) then can re-read in the same request via the agent loop. Users see stale results immediately after indexing, even though the API returned 200. The right shape is reading metadata from Supabase (authoritative) within the staleness window, or pinning reads after writes.
59+
validations:
60+
required: true
61+
62+
- type: textarea
63+
id: fix-sketch
64+
attributes:
65+
label: Proposed fix sketch
66+
description: 2-3 sentences OR write "needs ADR via /oci-design". Do not overdesign here.
67+
placeholder: needs ADR via /oci-design - the right consistency boundary is non-trivial
68+
69+
- type: textarea
70+
id: acceptance
71+
attributes:
72+
label: DDIA-aligned acceptance criteria
73+
description: Each criterion ties back to a DDIA principle. This is what makes the fix verifiably correct, not just "looks better."
74+
placeholder: |
75+
- [ ] Read-after-write within the same request returns the freshly indexed result (DDIA Ch 5 RYW guarantee)
76+
- [ ] Cross-session reads document staleness window in the ADR
77+
78+
- type: dropdown
79+
id: reliability
80+
attributes:
81+
label: Reliability impact
82+
description: How badly does the current state hurt reliability (DDIA Ch 1 pillar)?
83+
options:
84+
- none
85+
- minor
86+
- major
87+
- critical
88+
validations:
89+
required: true
90+
91+
- type: dropdown
92+
id: scalability
93+
attributes:
94+
label: Scalability impact
95+
description: How badly does the current state hurt scalability?
96+
options:
97+
- none
98+
- minor
99+
- major
100+
- critical
101+
validations:
102+
required: true
103+
104+
- type: dropdown
105+
id: maintainability
106+
attributes:
107+
label: Maintainability impact
108+
description: How badly does the current state hurt maintainability?
109+
options:
110+
- none
111+
- minor
112+
- major
113+
- critical
114+
validations:
115+
required: true
116+
117+
- type: input
118+
id: notes
119+
attributes:
120+
label: Chapter notes file
121+
description: Path to your chapter notes for cross-reference.
122+
placeholder: "learning/ddia/chapter-5.md"

‎.github/ISSUE_TEMPLATE/dogfood-finding.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: Dogfood Finding
2+
description: A friction you hit while using OCI's own MCP tools to build OCI. Capture in 60 seconds. Triage later.
3+
title: "[dogfood] "
4+
labels: ["dogfood-finding", "state/backlog", "type/fix"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Dogfooding is the forcing function. When OCI's own tools fail you mid-build, file it here in 60 seconds and keep coding. Triage happens during the Sunday `/oci-dogfood` review.
10+
11+
- type: textarea
12+
id: tried
13+
attributes:
14+
label: What I tried
15+
description: The exact tool call or workflow that triggered the friction.
16+
placeholder: |
17+
codeintel:search_code({
18+
"query": "where authentication happens",
19+
"repo_id": "78aa181e-2bbb-438b-97ee-9ffd494c4815"
20+
})
21+
validations:
22+
required: true
23+
24+
- type: textarea
25+
id: happened
26+
attributes:
27+
label: What happened
28+
description: Wrong result, slow result, error, or surprising behavior. Paste output if useful.
29+
placeholder: Returned 50 results across non-auth files. The actual auth code at `backend/middleware/auth.py` was not in the top 20.
30+
validations:
31+
required: true
32+
33+
- type: textarea
34+
id: expected
35+
attributes:
36+
label: What I expected
37+
description: What would have been useful.
38+
placeholder: "`backend/middleware/auth.py` in the top 3 results, since it has 'auth' in the path and contains the auth functions."
39+
validations:
40+
required: true
41+
42+
- type: textarea
43+
id: repro
44+
attributes:
45+
label: Repro steps
46+
description: Minimal steps for someone else (or future-you) to reproduce.
47+
placeholder: |
48+
1. cd into OCI repo, ensure MCP server is connected
49+
2. Call codeintel:search_code with the query above
50+
3. Note auth.py is not in the top results
51+
validations:
52+
required: true
53+
54+
- type: dropdown
55+
id: tool
56+
attributes:
57+
label: Which OCI tool
58+
description: The MCP tool that misbehaved.
59+
options:
60+
- codeintel:search_code
61+
- codeintel:get_codebase_dna
62+
- codeintel:analyze_impact
63+
- codeintel:get_dependencies
64+
- other (specify in body)
65+
validations:
66+
required: true
67+
68+
- type: checkboxes
69+
id: stack
70+
attributes:
71+
label: Stack the fix likely lives in
72+
description: Best guess. Reviewer-arch will refine during triage.
73+
options:
74+
- label: backend
75+
- label: frontend
76+
- label: mcp-server
77+
- label: cross-cutting
78+
79+
- type: textarea
80+
id: hypothesis
81+
attributes:
82+
label: Hypothesis (optional)
83+
description: If you have a guess about the root cause, capture it so future-you does not re-derive.
84+
placeholder: Search reranker weights "auth" too literally and misses semantic matches. Or include_paths filter is dropping middleware/.

‎.github/ISSUE_TEMPLATE/oci-issue.yml‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
name: OCI Issue (internal)
2+
description: Track an OCI work item (feat / refactor / chore / docs). For external bug reports use Bug Report; for external feature requests use Feature Request.
3+
title: "[OCI] "
4+
labels: ["state/backlog"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Internal OCI work tracker. Every issue here is a candidate for the OCI pipeline (`/oci-design` → `/oci-implement` → `/oci-pipeline` → `/oci-defend` → merge → `/oci-merge-done`).
10+
11+
Be specific. Vague issues do not earn ADRs and they do not ship.
12+
13+
- type: textarea
14+
id: why
15+
attributes:
16+
label: Why this exists
17+
description: What forces this work? Tie to a Wave priority, a dogfood-finding, a DDIA-finding, a customer report, or a security/perf bound that has been hit. One paragraph. No "we want to improve X" - name what changes if we do not ship this.
18+
placeholder: |
19+
Search latency is 3.6s p95 (OPE-121). MCP tools used in agent loops have a 500ms budget. Without fixing this, the search MCP tool is unusable inline and Greptile / Solid integrations are dead on arrival.
20+
validations:
21+
required: true
22+
23+
- type: textarea
24+
id: what
25+
attributes:
26+
label: What ships
27+
description: Concrete deliverables, one per bullet. Each bullet is ONE file change or ONE user-visible behavior. Do not bundle.
28+
placeholder: |
29+
- Replace Cohere reranker with the on-prem cross-encoder in `backend/services/search/rerank.py`
30+
- Add `RERANKER_BACKEND` env var to `backend/config/startup_checks.py` (warning only)
31+
- Update `mcp-server/api_client.py` to surface reranker name in tool response metadata
32+
validations:
33+
required: true
34+
35+
- type: textarea
36+
id: acceptance
37+
attributes:
38+
label: Acceptance criteria
39+
description: Testable outcomes only. Either a unit test exists OR a manual repro is documented. "Looks good" is not a criterion. "p95 latency under 500ms on /api/v1/search" is.
40+
placeholder: |
41+
- [ ] `/api/v1/search` p95 < 500ms measured over 100 requests on the OCI-on-OCI corpus
42+
- [ ] Reranker name appears in MCP tool response metadata
43+
- [ ] Backend tests pass: `cd backend && pytest tests/ -v`
44+
validations:
45+
required: true
46+
47+
- type: dropdown
48+
id: wave
49+
attributes:
50+
label: Wave
51+
description: Which OCI thesis wave does this serve? `pre-thesis` if filed before `oci/strategy.md` is locked.
52+
options:
53+
- pre-thesis
54+
- "1"
55+
- "2"
56+
- "3"
57+
validations:
58+
required: true
59+
60+
- type: dropdown
61+
id: type
62+
attributes:
63+
label: Type
64+
description: Matches commit-message type. Apply the corresponding label after filing.
65+
options:
66+
- feat
67+
- fix
68+
- refactor
69+
- perf
70+
- docs
71+
- test
72+
- chore
73+
validations:
74+
required: true
75+
76+
- type: checkboxes
77+
id: stack
78+
attributes:
79+
label: Stack scope
80+
description: Which stacks does this touch? Tick all that apply.
81+
options:
82+
- label: backend
83+
- label: frontend
84+
- label: mcp-server
85+
- label: cross-cutting (ADR / vault / docs / multi-stack)
86+
87+
- type: dropdown
88+
id: priority
89+
attributes:
90+
label: Priority
91+
options:
92+
- urgent
93+
- high
94+
- medium
95+
- low
96+
default: 2
97+
validations:
98+
required: true
99+
100+
- type: dropdown
101+
id: adr
102+
attributes:
103+
label: ADR required?
104+
description: Yes for any feat or non-trivial change. No for small fixes / docs / chore. The OCI pipeline refuses to start `/oci-implement` if `adr-required` is set and no ADR exists.
105+
options:
106+
- "yes - run /oci-design before /oci-implement"
107+
- "no - under ADR threshold"
108+
validations:
109+
required: true
110+
111+
- type: textarea
112+
id: dogfooding
113+
attributes:
114+
label: Dogfooding signal
115+
description: Did using OCI on OCI surface this need? If yes, link the moment or describe the failure. If no, write "no - filed from {plan / brainstorm / customer / regression / DDIA reading}".
116+
placeholder: "yes - codeintel:search_code returned irrelevant results when I queried 'auth fallback path' while debugging Bug #1"
117+
118+
- type: textarea
119+
id: related
120+
attributes:
121+
label: Related
122+
description: Wave milestone (when thesis locks), prior ADRs, linked issues, external references.
123+
placeholder: |
124+
- Wave: pre-thesis (Phase 1 pipeline work)
125+
- Prior ADRs: n/a
126+
- Linked: #
127+
- External: DDIA Ch 1 percentile-vs-average discussion

0 commit comments

Comments
 (0)