Apply code-commenting style guide across codebase #64

New Issue

2026-05-12T19:20:41Z

KofTwentyTwo commented

2026-05-12 19:20:41 +00:00

(Migrated from github.com)

Goal

Bring the codebase up to the standard defined in .planning/code-commenting-guide.md (commit b763273). Adversarial benchmark: a new dev opening any file understands WHY each non-obvious line exists in 30 seconds, without opening Plan ledgers or PR descriptions.

Scope

Sequenced rewrite. Each file = ONE atomic commit. Each tier = one issue below; close as the commits land.

Tier sequence

P0: AppDelegate.swift (the steepest cliff)
P1: AgentOrchestrator, WebviewBridge, MCPRuntime, MCPClient (load-bearing actors)
P2: Voice / Vision / Memory load-bearing actors
P3: Leaf packages opportunistically (per-PR convention)

Definition of done

Per-file: file header + type docstrings + method docstrings on public API + MARK dividers as TOC + "Before you edit" invariants block where applicable + ASCII diagram if orchestration/state-machine. Anti-patterns from the guide removed: no Plan-ID-only comments, no stale comments, no bare TODO/FIXME without issue+plan.
Project-wide: a grep gate scripts/check-no-stale-plan-id-comments.sh flags Plan-ID-only comment blocks (warn-level initially).
CLAUDE.md TL;DR section referencing the guide.

Effort estimate

~12 focused hours total per the guide's migration plan.

Sub-issues

P0: #65 — App/AppDelegate.swift
P1: #66 (AgentOrchestrator), #67 (WebviewBridge), #68 (MCPRuntime), #69 (MCPClient)
P2: #70 (Voice actors), #71 (Memory actors), #72 (Vision actors)
P3: #73 — leaf packages (opportunistic)
Tooling: #74 — scripts/check-no-stale-plan-id-comments.sh grep gate
CLAUDE.md TL;DR: #75 — load principles into default agent context

## Goal Bring the codebase up to the standard defined in `.planning/code-commenting-guide.md` (commit b763273). Adversarial benchmark: a new dev opening any file understands WHY each non-obvious line exists in 30 seconds, without opening Plan ledgers or PR descriptions. ## Scope Sequenced rewrite. Each file = ONE atomic commit. Each tier = one issue below; close as the commits land. ## Tier sequence - **P0:** AppDelegate.swift (the steepest cliff) - **P1:** AgentOrchestrator, WebviewBridge, MCPRuntime, MCPClient (load-bearing actors) - **P2:** Voice / Vision / Memory load-bearing actors - **P3:** Leaf packages opportunistically (per-PR convention) ## Definition of done - Per-file: file header + type docstrings + method docstrings on public API + MARK dividers as TOC + "Before you edit" invariants block where applicable + ASCII diagram if orchestration/state-machine. Anti-patterns from the guide removed: no Plan-ID-only comments, no stale comments, no bare TODO/FIXME without issue+plan. - Project-wide: a grep gate `scripts/check-no-stale-plan-id-comments.sh` flags Plan-ID-only comment blocks (warn-level initially). - `CLAUDE.md` TL;DR section referencing the guide. ## Effort estimate ~12 focused hours total per the guide's migration plan. ## Sub-issues - **P0:** #65 — App/AppDelegate.swift - **P1:** #66 (AgentOrchestrator), #67 (WebviewBridge), #68 (MCPRuntime), #69 (MCPClient) - **P2:** #70 (Voice actors), #71 (Memory actors), #72 (Vision actors) - **P3:** #73 — leaf packages (opportunistic) - **Tooling:** #74 — `scripts/check-no-stale-plan-id-comments.sh` grep gate - **CLAUDE.md TL;DR:** #75 — load principles into default agent context

KofTwentyTwo commented

2026-05-12 20:08:45 +00:00

(Migrated from github.com)

P0 (#65) done in commit 281b909. Pattern proven; P1 issues (#66-#69) are unblocked.

P0 (#65) done in commit 281b909. Pattern proven; P1 issues (#66-#69) are unblocked.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: KofTwentyTwo/Jarvis#64