plain-talk
Codebase analysis with A-F grades explained in plain language for non-technical stakeholders. Self-contained iOS/Swift audit. Triggers: "plain talk", "plain talk report card", "stakeholder report", "non-technical audit".
Terry Nyberg · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Terryc21/sitrep --skill plain-talkAbout this skill
name: plain-talk description: 'Codebase analysis with A-F grades explained in plain language for non-technical stakeholders. Self-contained iOS/Swift audit. Triggers: "plain talk", "plain talk report card", "stakeholder report", "non-technical audit".' version: 3.1.0 author: Terry Nyberg license: Apache-2.0 allowed-tools: [Glob, Grep, Read, Write, AskUserQuestion] metadata: tier: analysis category: analysis
Plain-Talk Report Card Generator
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Generate a codebase report card with A-F grades explained in plain, non-technical language for project managers, executives, or non-developer stakeholders.
All findings use the Issue Rating Table format. Include a brief plain-language explanation above the table so non-technical readers understand what the columns mean.
Step 1: Before Starting
📖 Run the opening interview from ../shared/session-setup.md § Opening interview.
It defines the CLAUDE.md and Timeline questions (plus the timeline grading adjustment)
shared by all report-card skills.
Focus question — specific to this skill. Use this as the third question:
{
"question": "Any areas to emphasize?",
"header": "Focus",
"options": [
{"label": "Standard analysis (Recommended)", "description": "Cover all categories equally"},
{"label": "Emphasize user experience", "description": "Focus on what users see and feel"},
{"label": "Emphasize reliability", "description": "Focus on crashes, errors, data safety"},
{"label": "Emphasize accessibility", "description": "Focus on usability for all users"}
],
"multiSelect": false
}
CLAUDE.md summary depth for this skill: 2-3 non-technical bullets — no framework names or API references.
Freshness
📖 Read ../shared/scan-discipline.md § Freshness and follow it. In short: current
source only, never .agents//scratch//prior reports, with one exception for reading a
previous report's grades only in Step 2. The shared file is authoritative — do not
re-inline the rule here.
Step 2: Trend Check
Check for a previous report to show improvement over time:
Glob pattern=".agents/research/*-plain-reportcard.md"
If found, read ONLY the grade summary line from the most recent report. Do not read or reuse any findings.
Step 3: Understand the App
Before scanning for issues, understand what this app does:
- What is it? — Read the app entry point and 2-3 key views to understand the purpose
- Who uses it? — Consumer app, business tool, utility, game?
- How big is it? — File count, approximate lines of code
- Key features — List 3-5 main things users do in the app
This context shapes how findings are explained in plain language.
Step 4: Automated Scans
Run all grep patterns below. Every finding MUST be verified by reading the flagged file before reporting — see Step 5.
4.1 User Experience
# Loading states — does the app show feedback during waits?
Grep pattern="ProgressView|\.loading|isLoading" glob="**/*.swift" output_mode="files_with_matches"
# Error handling — does the app show friendly error messages?
Grep pattern="(alert|errorMessage|showError)" glob="**/*.swift" output_mode="files_with_matches"
# Empty states — what happens when there's no data?
Grep pattern="(emptyState|EmptyView|ContentUnavailableView|noItems)" glob="**/*.swift" output_mode="files_with_matches"
# View complexity — large views may indicate poor UX structure
# Read flagged files and check if view body exceeds ~80 lines
Grep pattern="var body.*some View" glob="**/*View*.swift" output_mode="files_with_matches"
4.2 Reliability
# Force casts — can cause crashes if data is unexpected
# FALSE POSITIVE: as! after guard let or is check is already validated
Grep pattern="as!" glob="**/*.swift"
# Bare try? — silently ignores errors that users should know about
# FALSE POSITIVE: try? where nil is the expected/designed fallback
# INTENTIONAL: try? for operations where failure is acceptable (e.g., deleting a file that may not exist)
Grep pattern="try\?" glob="**/*.swift"
# Error handling coverage
Grep pattern="catch\s*\{" glob="**/*.swift" output_mode="files_with_matches"
# Data backup/sync support
Grep pattern="(CloudKit|iCloud|backup|BackupManager)" glob="**/*.swift" output_mode="files_with_matches"
4.3 Accessibility
# Fixed font sizes — breaks system text size preferences
# INTENTIONAL: some hardcoded sizes prevent clipping in constrained containers (e.g., badges, icons)
# Read each hit — classify as CONFIRMED (should migrate) or INTENTIONAL (constrained layout)
Grep pattern="\.font\(\.system\(size:" glob="**/*.swift"
# Accessibility label coverage
Grep pattern="\.accessibilityLabel" glob="**/*.swift" output_mode="count"
# Images needing descriptions for screen readers
# Read each — decorative images should use .accessibilityHidden(true)
Grep pattern="Image\(\"" glob="**/*.swift"
Grep pattern="Image\(systemName:" glob="**/*.swift"
# Testing support (accessibility identifiers)
Grep pattern="\.accessibilityIdentifier" glob="**/*.swift" output_mode="count"
4.4 Security
# Hardcoded secrets — passwords/keys visible in code
Grep pattern="(api[_-]?key|apikey|secret[_-]?key|client[_-]?secret|password|token)\s*[:=]\s*[\"'][^\"']+[\"']" glob="**/*.swift" -i
# Sensitive data stored insecurely (should be in Keychain)
Grep pattern="(UserDefaults|@AppStorage).*\b(password|token|secret|apiKey|credential)" glob="**/*.swift" -i
# Unencrypted connections
# FALSE POSITIVE: http://localhost, XML namespaces
Grep pattern="http://" glob="**/*.swift"
# Secure storage usage (positive signal)
Grep pattern="(Keychain|SecItem|kSecClass)" glob="**/*.swift" output_mode="files_with_matches"
# Privacy manifest (required for App Store)
Glob pattern="**/PrivacyInfo.xcprivacy"
4.5 Performance
# @Query without predica
Read the complete source ↗