update-design-audits

Skill: Update Design Audit Files

When to use this skill

Use this skill when asked to update the cross-platform design audit documents in standards/audits/ with recent pull request activity from the meshtastic/Meshtastic-Apple and/or meshtastic/Meshtastic-Android repositories. Typical triggers:

• "Update the audit files with the last N days of PRs"
• "Refresh the audits"
• Anything mentioning [ALIGNMENT] tags — those are the highest priority

---

The Four Audit Files

All files live under standards/audits/ in the meshtastic/design repository.

1. menu-alignment-audit.md

Tracks cross-platform navigation surface alignment (tab order, context menus, node detail views, etc.). Each section that has active work includes a Tracking table listing the GitHub issues and, once resolved, the merged PRs.

What to update:

• When a tracking issue is closed by a merged PR, add a PR column and Status column to the tracking table and mark ✅ Merged YYYY-MM-DD.
• Check the PR title and linked issue number to confirm it resolves the specific section.
• PR titles for this file typically contain: [ALIGNMENT], tab, navigation, context menu, node list, rename, reorder.

2. settings-validation-matrix.md

Tracks which settings screens and fields exist on each platform, along with validation constraint alignment. Sources are in standards/audits/data/.

What to update:

• §1 Screen Coverage tables — when a screen or field is added to a platform, change ❌ to ✅ and add a PR link/note.
• §2 Screens Only on Android — when Apple adds a previously Android-only screen, add — ✅ Now on both platforms to the section header and note the Apple PR.
• §3 Field-level mismatches — when a gap is closed, update the Discrepancy column to ✅ Fixed with the PR link and date.
• §4 Discrepancy Summary — strike through resolved rows using ~~text~~ and add PR reference.
• §5 Deprecated field handling — Items in §5.7 summary matrix: when an item is resolved, change ❌ / ⚠️ to ✅ Fixed (PR #XXXX).
• Update Last Updated date at the top of the file.
• PR titles for this file typically contain: field names (compass_orientation, air_quality, ntp_server), config, validation, missing fields.

3. cross-platform-spec-audit.md

Tracks SpecKit feature specifications across both platforms — what's specced, in-progress, or implemented.

What to update:

• Feature Specification Matrix — when a feature's status changes (Draft → Implemented, In Progress → Implemented), update the status cell with the merged PR link and date.
• Cross-Platform Gaps — when a gap is closed (e.g. a spec is written for the missing platform), strike through the row with ~~text~~ and note ✅ Gap closed — PR #XXXX.
• "Features nearing merge" table — remove rows for features that have now merged to main.
• Update Last Updated date at the top.
• PR titles for this file typically contain: spec names (TAK v2, M3 Expressive, message formatting, lockdown), spec, SpecKit.

4. community-alignment-matrix.md

Maps open design repo issues against community opinion and Design Standards v1.4.

What to update:

• Update the Date header at the top.
• For issues where implementation PRs have merged, add a note to the relevant row with the PR links and what was resolved.
• Update Key Takeaways bullet points for issues that have had significant progress.
• Do not close or remove issues from the matrix unless the design issue itself is closed.
• PR titles for this file typically mention issue numbers or topic areas that match issue descriptions.

---

Step-by-Step Update Process

1. Create a branch

git checkout -b audits/YYYY-MM-update

Always work on a branch — never commit directly to master.

2. Fetch recent PRs from both repos

# Apple PRs (last 30 days)
gh pr list --repo meshtastic/Meshtastic-Apple \
  --state merged --limit 80 \
  --json number,title,mergedAt,body | \
  jq '.[] | select(.mergedAt > "YYYY-MM-DDT00:00:00Z")'

# Android PRs (last 30 days)
gh pr list --repo meshtastic/Meshtastic-Android \
  --state merged --limit 100 \
  --json number,title,mergedAt | \
  jq '.[] | select(.mergedAt > "YYYY-MM-DDT00:00:00Z")'

Replace YYYY-MM-DD with the date 30 days ago.

3. Categorize PRs by audit file

Scan each PR title and sort into buckets:

Keyword(s) in title	Likely affects
[ALIGNMENT], tab, navigation, context menu, reorder, rename tab	menu-alignment-audit.md
config, validation, missing field, field name (e.g. compass_orientation, ntp_server, air_quality)	settings-validation-matrix.md
spec, SpecKit, feature name (TAK v2, M3 Expressive, lockdown)	cross-platform-spec-audit.md
Issue numbers #83, #99, #100, unit/locale, translate, measurement	community-alignment-matrix.md

When a PR title is ambiguous, run:

gh pr view PRNUM --repo meshtastic/Meshtastic-Apple

to read the body and linked issues.

4. For each relevant PR, determine the specific change

For settings PRs, read the PR body or diff to identify:

• Which screen was changed
• Which specific fields were added/fixed/removed
• What the new constraint/validation is

For alignment PRs, confirm:

• Which audit section the PR addresses (§1, §3, etc.)
• The exact issue number the PR closes

5. Edit the audit files

Apply changes using the patterns described in each file's section above. Key conventions:

• Use ✅ for resolved/implemented
• Use ⚠️ for partial or platform-conditional
• Use ❌ for missing/broken
• Use ~~strikethrough~~ for items that are no longer applicable
• Always include a PR link: [#1234](https://github.com/meshtastic/Meshtastic-Apple/pull/1234)
• Always include the merge date: (YYYY-MM-DD)

6. Commit and push

git add standards/audits/
git commit -m "audits: MONTH YEAR update — summary of changes

[ALIGNMENT] menu-alignment-audit: (if changed)
- §N: mark resolved — Apple PR #XXXX, Android PR #XXXX

settings-validation-matrix:
- Last Updated: YYYY-MM-DD
- (bullet each changed row)

cross-platform-spec-audit:
- (bullet each changed cell)

community-alignment-matrix:
- Date: MONTH DD, YYYY
- (bullet each updated issue)"

git push -u origin audits/YYYY-MM-update

7. Create a PR

gh pr create \
  --repo meshtastic/design \
  --base master \
  --title "audits: MONTH YEAR update — Apple/Android PRs" \
  --body "Updates all 4 audit files in \`standards/audits/\` based on PR activity from the last 30 days.

## Changes
### menu-alignment-audit.md
- ...

### settings-validation-matrix.md
- ...

### cross-platform-spec-audit.md
- ...

### community-alignment-matrix.md
- ..."

---

Important Conventions

[ALIGNMENT] tag

Any PR or issue marked [ALIGNMENT] in its title/label tracks cross-platform UX parity work. These are highest priority to capture in the audit. Always update menu-alignment-audit.md and the relevant field/screen rows in settings-validation-matrix.md.

Status marker cheat sheet

Symbol	Meaning
✅	Present/implemented/fixed on this platform
⚠️	Present but with known issues or partial implementation
❌	Missing or broken on this platform
🔴 Branch Complete	Spec/feature complete on branch, awaiting merge
🔵 In Progress	Implementation underway, tasks partially done
🔵 Draft	Spec written, implementation not started
~~text~~	Struck through — no longer applicable, resolved, or removed

Linking format

Always use inline markdown links:

✅ **Fixed** in Apple PR [#1847](https://github.com/meshtastic/Meshtastic-Apple/pull/1847) (2026-05-21)

Data files

The detailed per-platform validation references live in standards/audits/data/:

• settings-validation-android.md — Android validation rules per screen/field
• settings-validation-apple.md — Apple validation rules per screen/field

When an Android or Apple validation rule changes, update the appropriate data file and the matrix.

---

Reference: Repo URLs

Resource	URL
Apple repo	https://github.com/meshtastic/Meshtastic-Apple
Android repo	https://github.com/meshtastic/Meshtastic-Android
Design repo	https://github.com/meshtastic/design
Design standards (latest)	standards/meshtastic_design_standards_latest.md