Skip to content

Commit a401853

Browse files
authored
Reduce ambient prompt surface in high-traffic workflows (#40695)
1 parent 4bb6180 commit a401853

7 files changed

Lines changed: 49 additions & 340 deletions

.github/agents/adr-writer.agent.md

Lines changed: 0 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,6 @@ docs/adr/
3434

3535
## ADR Template
3636

37-
Two parts: **human-friendly narrative**, then **RFC 2119 normative specification** for machine-checkable conformance.
38-
3937
```markdown
4038
# ADR-{NNNN}: {Concise Decision Title}
4139

@@ -45,8 +43,6 @@ Two parts: **human-friendly narrative**, then **RFC 2119 normative specification
4543

4644
---
4745

48-
## Part 1 — Narrative (Human-Friendly)
49-
5046
### Context
5147

5248
{Describe the situation, problem, and forces at play in plain language. What is the issue that motivated this decision? What constraints exist? What are the non-negotiable requirements? Write for a developer who is new to the codebase and needs background without reading the code. Keep this to 3–5 sentences.}
@@ -83,28 +79,6 @@ Two parts: **human-friendly narrative**, then **RFC 2119 normative specification
8379

8480
---
8581

86-
## Part 2 — Normative Specification (RFC 2119)
87-
88-
> The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this section are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
89-
90-
### {Primary requirement area — e.g., "Data Storage", "API Design", "Authentication"}
91-
92-
1. Implementations **MUST** {the non-negotiable core of the decision in imperative form}.
93-
2. Implementations **MUST NOT** {what is explicitly prohibited by this decision}.
94-
3. Implementations **SHOULD** {what is strongly recommended but has valid exceptions}.
95-
4. Implementations **MAY** {what is permitted but not required}.
96-
97-
### {Secondary requirement area, if applicable}
98-
99-
1. {Additional normative requirement}.
100-
2. {Additional normative requirement}.
101-
102-
### Conformance
103-
104-
An implementation is considered conformant with this ADR if it satisfies all **MUST** and **MUST NOT** requirements above. Failure to meet any **MUST** or **MUST NOT** requirement constitutes non-conformance.
105-
106-
---
107-
10882
*ADR created by [adr-writer agent]. Review and finalize before changing status from Draft to Accepted.*
10983
```
11084

@@ -120,8 +94,6 @@ An implementation is considered conformant with this ADR if it satisfies all **M
12094

12195
## Writing Quality Standards
12296

123-
### Part 1 — Narrative Sections
124-
12597
#### Context (3–5 sentences)
12698
- *What problem? What constraints?* (technical, organizational, timeline)
12799
- Codebase state at decision time
@@ -143,31 +115,6 @@ An implementation is considered conformant with this ADR if it satisfies all **M
143115
- **Neutral**: side effects worth noting
144116
- ≥2 per category for non-trivial decisions
145117

146-
### Part 2 — Normative Specification
147-
148-
Translates the Decision into testable [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) requirements.
149-
150-
#### RFC 2119 Keyword Usage
151-
152-
| Keyword | Use when… |
153-
|---------|-----------|
154-
| **MUST** / **REQUIRED** / **SHALL** | Absolute, non-negotiable constraint |
155-
| **MUST NOT** / **SHALL NOT** | Absolute prohibition |
156-
| **SHOULD** / **RECOMMENDED** | Strong recommendation; valid exceptions may exist |
157-
| **SHOULD NOT** / **NOT RECOMMENDED** | Strong discouragement; valid exceptions may exist |
158-
| **MAY** / **OPTIONAL** | Truly optional |
159-
160-
#### Writing Normative Requirements
161-
162-
- Complete sentences ending with a period
163-
- Keywords (**MUST**, **SHOULD**, **MAY**, etc.) in **bold**
164-
- Atomic — one constraint per numbered item
165-
- Group into named subsections (e.g., "Storage", "API", "Authentication")
166-
- Every section ends with a **Conformance** paragraph
167-
- Stay consistent with the narrative Decision
168-
- "We will always use X" → "Implementations **MUST** use X"
169-
- "We prefer Y" → "Implementations **SHOULD** use Y"
170-
171118
## Procedure: Writing a New ADR
172119

173120
### Step 1: Next Sequence Number
@@ -206,7 +153,6 @@ Write to `docs/adr/{NNNN}-{title}.md`.
206153

207154
### Step 7: Validate
208155

209-
**Part 1 — Narrative:**
210156
- [ ] Context, Decision, Alternatives, Consequences sections all present
211157
- [ ] Status is `Draft` for new ADRs
212158
- [ ] Date is today (YYYY-MM-DD format)
@@ -215,14 +161,6 @@ Write to `docs/adr/{NNNN}-{title}.md`.
215161
- [ ] Filename follows NNNN-kebab-case-title.md convention
216162
- [ ] ADR number in title matches filename number
217163

218-
**Part 2 — Normative Specification:**
219-
- [ ] RFC 2119 boilerplate paragraph present
220-
- [ ] All normative keywords in **bold**
221-
- [ ] Each requirement atomic (one constraint per item)
222-
- [ ] Requirements grouped into named subsections
223-
- [ ] Conformance paragraph present
224-
- [ ] Normative requirements are consistent with the narrative Decision section
225-
226164
## Procedure: Analyzing a PR Diff for ADR Content
227165

228166
Look for:

0 commit comments

Comments
 (0)