Skip to content

Commit b3bc1ab

Browse files
brendanjryangakonstjbransvisajxomk15z
committed
init
Co-authored-by: Brendan Ryan <brendanjryan@users.noreply.github.com> Co-authored-by: Georgios Konstantopoulos <me@gakonst.com> Co-authored-by: jbransvisa <55891199+jbransvisa@users.noreply.github.com> Co-authored-by: jxom <7336481+jxom@users.noreply.github.com> Co-authored-by: Kevin Zhang <kevin.2015.zhang@gmail.com> Co-authored-by: Steve Kaliski <59668283+stevekaliski-stripe@users.noreply.github.com> Co-authored-by: tmm <tom@meagher.co>
0 parents  commit b3bc1ab

49 files changed

Lines changed: 12866 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/reviewing-ietf-drafts/SKILL.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
---
2+
name: reviewing-ietf-drafts
3+
description: Reviews and critiques IETF Internet-Drafts and RFC submissions for style compliance, technical clarity, prior art gaps, and publication readiness. Use when analyzing existing drafts or providing editorial feedback.
4+
requires:
5+
- writing-ietf-w3c-specs
6+
---
7+
8+
# IETF Draft Reviewer
9+
10+
Systematic review of Internet-Drafts for RFC publication readiness.
11+
12+
## When to Use
13+
14+
Use this skill when:
15+
- Reviewing an existing Internet-Draft before submission
16+
- Providing editorial feedback on a colleague's draft
17+
- Checking your own draft against IETF requirements
18+
- Evaluating a draft for technical clarity and completeness
19+
20+
## Review Methodology
21+
22+
### Phase 1: Structural Scan
23+
24+
Quick pass to verify all required elements are present.
25+
26+
| Element | Required? | Check |
27+
|---------|-----------|-------|
28+
| Abstract | Yes | Self-contained, no citations |
29+
| Requirements Language (RFC 2119) | If keywords used | Boilerplate in Section 2 |
30+
| Terminology | If domain-specific terms | Definitions before first use |
31+
| Security Considerations | Always | Substantive content |
32+
| IANA Considerations | Always | Even if "no actions" |
33+
| Internationalization | If applicable | Character sets, localization |
34+
| References | Yes | Normative/Informative split |
35+
36+
### Phase 2: Style Compliance (RFC 7322)
37+
38+
Detailed review against RFC Style Guide.
39+
40+
#### Requirement Keywords
41+
42+
| Issue | Example | Severity |
43+
|-------|---------|----------|
44+
| Lowercase normative | "should validate" | HIGH - change to SHOULD |
45+
| MUST in informational text | "Users MUST read the docs" | MEDIUM - use lowercase |
46+
| Ambiguous modal | "may or may not" | HIGH - clarify intent |
47+
| Missing RFC 2119 reference | Keywords used, no boilerplate | HIGH - add Section 2 |
48+
49+
#### Citation Format
50+
51+
| Wrong | Correct |
52+
|-------|---------|
53+
| `[1]` | `[RFC2119]` |
54+
| `(see page 5)` | `(see Section 3.1)` |
55+
| `RFC 2119` inline | `[RFC2119]` |
56+
| Mixed normative/informative | Separate reference sections |
57+
58+
#### Text Format
59+
60+
| Issue | Recommendation |
61+
|-------|----------------|
62+
| Lines > 72 chars in diagrams | Reformat to fit |
63+
| Tabs in source | Convert to spaces |
64+
| Non-ASCII characters | Use ASCII equivalents or declare UTF-8 |
65+
| Orphan headers | Keep header with following paragraph |
66+
67+
### Phase 3: Technical Clarity
68+
69+
Evaluate whether the specification is implementable.
70+
71+
#### Precision Checklist
72+
73+
- [ ] All terms defined before first use
74+
- [ ] Numeric ranges explicit (inclusive/exclusive stated)
75+
- [ ] Units always specified ("30 seconds" not "timeout of 30")
76+
- [ ] Edge cases documented
77+
- [ ] Error conditions enumerated
78+
- [ ] Default values stated for optional parameters
79+
- [ ] State machines have defined transitions
80+
81+
#### Ambiguity Flags
82+
83+
| Pattern | Problem | Fix |
84+
|---------|---------|-----|
85+
| "appropriate" | Undefined | Specify criteria |
86+
| "reasonable" | Subjective | Give bounds |
87+
| "typically" | Non-normative | Use SHOULD or document exceptions |
88+
| "etc." | Incomplete | Enumerate or use "and others" |
89+
| "as needed" | Vague | Define triggers |
90+
91+
### Phase 4: Prior Art & Conflicts
92+
93+
#### Related Work Check
94+
95+
1. **RFC Search**: Does the draft cite all relevant existing RFCs?
96+
2. **I-D Search**: Any active drafts covering similar ground?
97+
3. **WG Conflict**: Is an IETF Working Group already addressing this?
98+
4. **Updates/Obsoletes**: If modifying existing RFC, is metadata correct?
99+
100+
#### Conflict Indicators
101+
102+
| Signal | Risk | Action |
103+
|--------|------|--------|
104+
| Active WG on same topic | High | May get DNP (Do Not Publish) |
105+
| Recent RFC in same area | Medium | Ensure proper citations |
106+
| Competing I-D | Medium | Differentiate or consolidate |
107+
| Patent mentions | Variable | Verify IPR disclosure |
108+
109+
### Phase 5: Publication Readiness
110+
111+
#### Stream Appropriateness
112+
113+
| Stream | Valid Status | Consensus Required |
114+
|--------|--------------|-------------------|
115+
| IETF | Standards Track, BCP, Info, Exp | Yes |
116+
| Independent | Informational, Experimental, Historic | No |
117+
| IRTF | Informational, Experimental | IRSG |
118+
| IAB | Informational | IAB |
119+
120+
#### Blocking Issues
121+
122+
| Issue | Impact | Resolution |
123+
|-------|--------|------------|
124+
| Normative ref to unpublished I-D | MISSREF state | Make informative or wait |
125+
| Missing IANA registry policy | Blocks publication | Add per RFC 8126 |
126+
| No Security Considerations | Rejected | Add substantive section |
127+
| IPR not disclosed | Legal risk | File IPR disclosure |
128+
129+
---
130+
131+
## Review Output Template
132+
133+
When reviewing a draft, produce a report with this structure:
134+
135+
```markdown
136+
# Review: draft-name-version
137+
138+
## Summary
139+
[One paragraph overall assessment]
140+
141+
## Structural Issues
142+
- [ ] Issue 1
143+
- [ ] Issue 2
144+
145+
## Style Violations
146+
| Location | Issue | Recommendation |
147+
|----------|-------|----------------|
148+
| Section X | ... | ... |
149+
150+
## Technical Clarity
151+
[Ambiguities, undefined terms, missing edge cases]
152+
153+
## Prior Art Gaps
154+
[Missing citations, potential conflicts]
155+
156+
## Publication Blockers
157+
[Issues that MUST be resolved before submission]
158+
159+
## Recommendations
160+
1. Priority fix 1
161+
2. Priority fix 2
162+
...
163+
```
164+
165+
---
166+
167+
## Common Issues by Section
168+
169+
### Abstract
170+
171+
| Issue | Example | Fix |
172+
|-------|---------|-----|
173+
| Contains citations | "as defined in [RFC9110]" | Remove, describe inline |
174+
| Undefined acronyms | "TLS" | Expand: "Transport Layer Security (TLS)" |
175+
| Too long | > 200 words | Condense to essential description |
176+
| Not self-contained | "See Section 3" | Remove cross-references |
177+
178+
### Security Considerations
179+
180+
| Issue | Example | Fix |
181+
|-------|---------|-----|
182+
| Empty/trivial | "No security considerations" | Never acceptable; find real issues |
183+
| Generic | Copy-paste boilerplate | Tailor to specific protocol |
184+
| Missing threat model | Lists attacks without context | Add threat model section |
185+
| No mitigations | Identifies risks, no solutions | Add recommended countermeasures |
186+
187+
**Required Coverage:**
188+
- Threat model assumptions
189+
- Authentication/authorization
190+
- Confidentiality/integrity
191+
- Replay protection
192+
- Denial of service
193+
- Privacy implications
194+
195+
### IANA Considerations
196+
197+
| Issue | Example | Fix |
198+
|-------|---------|-----|
199+
| Missing when needed | Defines new registry values | Add IANA section |
200+
| Wrong registration policy | Uses "First Come First Served" for security-sensitive | Use "Specification Required" |
201+
| Missing template | New registry without fields | Add registration template |
202+
| Placeholder not resolved | "TBD" in final draft | Get actual values |
203+
204+
### References
205+
206+
| Issue | Example | Fix |
207+
|-------|---------|-----|
208+
| Normative ref to I-D | Blocks on unpublished work | Reconsider dependency |
209+
| Missing DOI | RFC without DOI | Add DOI |
210+
| Outdated RFC | Cites obsoleted RFC | Update to current |
211+
| URL-only reference | External spec by URL only | Add full bibliographic entry |
212+
213+
---
214+
215+
## Quick Reference: Severity Levels
216+
217+
| Severity | Description | Action |
218+
|----------|-------------|--------|
219+
| BLOCKER | Prevents publication | Must fix before submission |
220+
| HIGH | Violates IETF requirements | Should fix, may cause IESG review issues |
221+
| MEDIUM | Style guide violation | Recommended fix |
222+
| LOW | Editorial suggestion | Optional improvement |
223+
224+
---
225+
226+
## Reviewer Workflow
227+
228+
```
229+
1. Read abstract and introduction
230+
└─> Understand scope and claims
231+
232+
2. Structural scan (Phase 1)
233+
└─> Verify all required sections present
234+
235+
3. Read Security and IANA sections
236+
└─> Most common failure points
237+
238+
4. Detailed style review (Phase 2)
239+
└─> Check RFC 7322 compliance
240+
241+
5. Technical deep-dive (Phase 3)
242+
└─> Implementability assessment
243+
244+
6. Prior art search (Phase 4)
245+
└─> Conflict and citation check
246+
247+
7. Publication assessment (Phase 5)
248+
└─> Stream appropriateness, blockers
249+
250+
8. Generate report
251+
└─> Use template, prioritize findings
252+
```
253+
254+
---
255+
256+
## References
257+
258+
- **RFC 7322**: RFC Style Guide
259+
- **RFC 7991**: xml2rfc v3 Vocabulary
260+
- **RFC 8126**: Guidelines for IANA Considerations
261+
- **RFC 2119 / 8174**: Requirements Language
262+
- **RFC Editor Publication Process**: https://www.rfc-editor.org/pubprocess/
263+
- **I-D Guidelines**: https://www.ietf.org/standards/ids/guidelines/

‎.dockerignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.git
2+
artifacts
3+
.DS_Store

‎.github/workflows/deploy.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Deploy
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: write
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: deploy
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build-deploy:
19+
runs-on: ubuntu-latest
20+
environment:
21+
name: github-pages
22+
url: ${{ steps.deployment.outputs.page_url }}
23+
steps:
24+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
25+
26+
- uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
27+
28+
- uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
29+
with:
30+
context: .
31+
load: true
32+
tags: ietf-spec-tools:latest
33+
cache-from: type=gha
34+
cache-to: type=gha,mode=max
35+
36+
- name: Generate artifacts
37+
run: |
38+
mkdir -p .cache
39+
docker run --rm --user $(id -u):$(id -g) -e HOME=/data -v ${{ github.workspace }}:/data ietf-spec-tools:latest /data/scripts/gen.sh
40+
41+
- name: Upload bundle
42+
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
43+
with:
44+
name: ietf-specs-${{ github.sha }}
45+
path: artifacts/
46+
retention-days: 90
47+
48+
- name: Publish spec artifacts as GitHub Release
49+
env:
50+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
51+
run: |
52+
gh release delete latest --yes --cleanup-tag 2>/dev/null || true
53+
gh release create latest artifacts/*.html artifacts/*.txt artifacts/*.xml artifacts/*.pdf \
54+
--title "Latest spec artifacts" \
55+
--notes "Auto-published spec build artifacts from commit ${{ github.sha }}.
56+
57+
Contains HTML, TXT, XML, and PDF renderings of all IETF Payment Auth specifications." \
58+
--latest
59+
60+
- name: Generate index page
61+
run: |
62+
docker run --rm --user $(id -u):$(id -g) -e HOME=/data -v ${{ github.workspace }}:/data ietf-spec-tools:latest python3 /data/scripts/gen_index.py
63+
64+
- name: Generate problem pages
65+
run: |
66+
docker run --rm --user $(id -u):$(id -g) -e HOME=/data -v ${{ github.workspace }}:/data ietf-spec-tools:latest python3 /data/scripts/gen_problems.py
67+
68+
- name: Prepare GitHub Pages
69+
run: |
70+
mkdir -p _site
71+
cp pages/index.html _site/
72+
cp -r pages/problems _site/problems
73+
cp artifacts/*.html artifacts/*.txt artifacts/*.xml artifacts/*.pdf _site/
74+
echo "paymentauth.org" > _site/CNAME
75+
76+
- name: Upload Pages artifact
77+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
78+
79+
- name: Deploy to GitHub Pages
80+
id: deployment
81+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

0 commit comments

Comments
 (0)