Dear Apple Contributor Agent
AI agent instructions for contributing to the Dear Apple documentation repository. This skill enables AI agents to productively assist with structural edits, consistency checks, and template compliance while following strict safety and governance rules.
What This Skill Does
This agent helps maintain documentation quality in the Dear Apple repository by:
Ensuring files follow canonical templates (`analyses/TEMPLATE.md` or `letters/TEMPLATE.md`)Performing consistency checks (duplicated sections, contradictory statements, missing fields)Improving clarity, grammar, and formatting consistencyCreating PRs with proper branch naming and descriptionsEnforcing repository-specific patterns and safety requirements**Repository focus:** Documentation-first repo for Apple platform observations and community letters. Primary artifacts live in `analyses/` and `letters/`.
Instructions
1. Understand Repository Structure
Primary content directories: `analyses/` and `letters/`Templates are canonical: `analyses/TEMPLATE.md` and `letters/TEMPLATE.md`File naming convention: `analyses/YYYY-MM-DD-short-title.md`Review `analyses/2025-12-24-macos-safari-external-link-routing-private-context.md` as canonical example2. Permitted Agent Actions
**Structural edits:**
Ensure files follow folder templates (headings, Observation status & confidence, Evidence, Open questions, Updates)Normalize headings and formatting to match existing style**Consistency checks:**
Detect duplicated sections, contradictory statements, missing template fieldsIdentify repeated reproduction steps**Editorial refinement:**
Improve clarity and fix grammarEnsure consistent formatting**Metadata management:**
Add "Author's note on methodology" header when missingAdd preface pointing to `AI_TOOLS_USAGE.md`Add neutral "Evidence (stub)" section when no logs exist, clearly labeled as hypothetical/unexecuted**PR creation:**
Use project pattern: `add/analysis-2025-12-24-safari-external-link`Ensure PR description follows repository's PR checklist (see `CONTRIBUTING.md`)3. Strictly Prohibited Actions
**NEVER do the following:**
Generate or fabricate observational data, logs, or test resultsCreate exploit code or publish steps that could enable harmful actionsMerge or accept PRs lacking required human-verified evidenceMerge PRs that fail to document uncertainty/confidence clearlyInclude PII (email addresses, IPs, serial numbers) in any content4. Required Template Fields
**Observation status & confidence block must include:**
Reproducible by authorReproduced on multiple devicesHardware dependency suspectedRegression vs previous versionsConfidence levelUncertainty summaryOpen questions**Reproduction steps:**
Use numbered list format exactly as in `TEMPLATE.md`Follow example block under "Reproduction steps (observed)" in existing analyses**Evidence section:**
Must exist even when emptyMark as `hypothesized` or `not yet executed` when applicableList minimal reproducible probe (e.g., cookie set + echo endpoint) when applicable5. Safety and Governance Rules
**PII handling:**
Redact all PII before committingFlag maintainers for help (see `DISCLAIMER.md`)**Security-sensitive content:**
Add note and follow `SECURITY.md` before public disclosureNever include exploit details without vendor-first disclosure**AI usage disclosure:**
Place short note in document header if AI tools assisted editoriallyFollow `AI_TOOLS_USAGE.md` for required language**Formatting standards:**
Prefer ASCII punctuation and plain text in technical contentAvoid non-ASCII punctuation (typographic quotes, en/em dashes) in `analyses/`, `letters/`, governance filesUse UTF-8 only for controlled, decorative contexts (document exceptions in PR)**Language requirement:**
Use English for all official repository contentOptional translations must supplement, not replace, English versionsDocument any intentional exceptions in PR description6. PR Checklist Validation
**Before submitting PR, validate:**
[ ] File placed under correct directory (`analyses/` or `letters/`)[ ] `TEMPLATE.md` headings present and complete[ ] `Observation status & confidence` block exists and is populated[ ] `Evidence` section exists and is clearly labeled (hypothesized/collected/attached)[ ] No PII patterns present (email addresses, IPs, serial numbers)[ ] If security-sensitive, `SECURITY.md` steps are referenced[ ] PR description follows checklist in `CONTRIBUTING.md` with required checkboxes7. When Uncertain
**If you cannot verify test results:**
Mark as `hypothesized`Add suggested minimal test (server echo, header/cookie probe) for human to runAsk reviewers to confirm provenance (who ran which test, on which hardware/OS)**For policy or governance questions:**
Reference `AI_TOOLS_USAGE.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`Open issue (without sensitive data) and request maintainer guidanceTag maintainers for redaction, sensitive disclosure, or legal questionsExample Usage
**Scenario 1: Structural compliance check**
```
Review all files in analyses/ and ensure they follow TEMPLATE.md structure.
Flag any missing required sections.
```
**Scenario 2: Create analysis document**
```
Create new analysis file analyses/2025-02-04-ios-webkit-cookie-issue.md
following TEMPLATE.md. Mark Evidence section as "hypothesized" and include
minimal reproduction steps suggestion for human verification.
```
**Scenario 3: PR preparation**
```
Create PR for branch add/analysis-2025-02-04-webkit-cookie with proper
description following CONTRIBUTING.md checklist. Ensure all template
fields are present and no PII is included.
```
Constraints
**Human verification required:** All technical observations must be attributed to human contributors who performed tests on real hardware**Security first:** Follow vendor-first disclosure for security findings**No fabrication:** Never generate fake logs, test results, or observational data**PII protection:** Redact all personally identifiable information**Template compliance:** Maintain strict adherence to canonical templates**English required:** Use English for all official repository contentKey Repository Files
`analyses/TEMPLATE.md` — Canonical template for analyses`letters/TEMPLATE.md` — Canonical template for letters`CONTRIBUTING.md` — Contribution guidelines and PR checklist`SECURITY.md` — Security disclosure process`AI_TOOLS_USAGE.md` — AI usage disclosure requirements`DISCLAIMER.md` — PII and legal disclaimers`CODE_OF_CONDUCT.md` — Community conduct guidelines---
**Priority:** Human verification over automation. When uncertain, mark as hypothesized and request human confirmation.