carehub-steering-docs-audit.md

Steering Docs Audit: CareHub Mobile (Notion)

Audit methodology: Every instruction evaluated against the CLAUDE.md filter — is it discoverable from existing files, vague, redundant across levels, or enforced by tooling? The default is empty; every line must justify its existence.

Inventory

All steering lives in Notion under CareHub > Docs And Specs. No local CLAUDE.md, AGENTS.md, SKILL.md, or agent.md files exist in the repository.

#	Document	Type	Notion ID
1	Spec Workflow Guide	Skill definition (for /sdd)	31024a22-...6096
2	Product Vision	Reference (steering)	30424a22-...71bc
3	Technology Stack	Reference (steering)	30424a22-...90a6
4	Project Structure	Reference (steering)	30424a22-...6c42
5	SDD Rules & Guidelines	Reference (process)	30424a22-...38da
6	Specification Creation Requirements	Reference (process)	30424a22-...c17d
7	Implementation Log Format	Template	31024a22-...1748
8	Requirements Document Template	Template	31024a22-...31d3
9	Design Document Template	Template	30424a22-...d599
10	Tasks Document Template	Template	31024a22-...f002e
11	Workflow Decision Tree	Reference	30424a22-...50ea
12	Figma UI Implementation	Template	30424a22-...9ed1f
13	ViewModel Patterns	Template	30424a22-...ed4e5
14	UseCase Patterns	Template	30424a22-...3a3543
15	DI Patterns (Koin)	Template	30424a22-...4f2911
16	KMP Module Structure	Template	30424a22-...e473f4a
17	Gradle Dependency Management	Template	30424a22-...5741fe6
18	Test Writing Standards	Reference (standards)	32224a22-...de56df
19	Testing Contract Template	Template	32224a22-...78ffab0

---

Document-by-Document CLAUDE.md Filter Audit

1. Technology Stack

#	Instruction	Verdict	Reasoning
1	"Kotlin Multiplatform mobile application targeting Android and iOS"	DELETE	Discoverable from settings.gradle.kts, build.gradle.kts, and directory structure in seconds
2	"Kotlin 2.2.20"	DELETE	Discoverable from libs.versions.toml (also stale — actual is 2.2.21)
3	"Compose Multiplatform 1.9.0"	DELETE	Discoverable from libs.versions.toml (also stale — actual is 1.10.1)
4	"Koin 4.1.1"	DELETE	Discoverable from libs.versions.toml
5	"Ktor 3.3.0"	DELETE	Discoverable from libs.versions.toml (stale — actual 3.3.2)
6	"Room 2.8.0"	DELETE	Discoverable from libs.versions.toml (stale — actual 2.8.4)
7	All other version numbers	DELETE	Same — libs.versions.toml is the source of truth. Duplicating versions guarantees staleness
8	"MVVM+MVI Architecture" description	SHARPEN	Architecture pattern is discoverable from code, but the choice and why isn't. Keep decision, delete description
9	"BaseViewModel Architecture: Centralized error handling"	DELETE	Discoverable from BaseViewModel.kt
10	ViewModel Interface Constraints (action methods, StateFlow, SideEffects only)	KEEP	Non-obvious hard constraint. Agent won't discover "PROHIBITED: direct data properties" from reading a few files
11	"STRICTLY PROHIBITED: Direct data properties, getter methods..."	KEEP	Specific, actionable, not enforced by tooling
12	Architecture Principles (1-5)	DELETE	Generic software engineering ("Separation of Concerns", "Testability"). Not actionable — every codebase claims these
13	Navigation Architecture description	DELETE	Discoverable from Router.kt and usage patterns. Also references Navigator which doesn't exist — stale
14	"Build System: Gradle 8.x with Kotlin DSL"	DELETE	Discoverable from gradlew, build.gradle.kts
15	"MANDATORY - All dependencies MUST use version catalog"	KEEP	Non-obvious constraint (many KMP projects use hardcoded versions)
16	"BOM pattern MANDATORY for Koin dependencies"	KEEP	Non-obvious, specific, prevents real build errors
17	"Static Analysis: Detekt 1.23.8"	DELETE	Discoverable from build.gradle.kts and libs.versions.toml
18	"Testing: Kotlin Test, Turbine 1.2.1, Mokkery 2.10.0"	DELETE	Discoverable from libs.versions.toml (also stale — Mokkery is 2.10.2)
19	CareHubTheme mandatory usage section	SHARPEN	Rule is KEEP but token names are wrong. CareHubColors.white → actual is CareHubColors.neutralWhite. CareHubTypography.bodyLarge → actual is different naming. Fix or remove examples
20	MaterialTheme Usage Prohibition	KEEP	Critical hard constraint, not enforced by linter
21	"Button {} → ChButton {}, Card {} → ChCard {}"	SHARPEN	ChCard and ChTextField don't exist in codebase. List only components that actually exist
22	Color token examples (CareHubColors.primary, .surface)	DELETE	Wrong — actual naming uses semantic prefixes (bgNeutralPrimary, etc.). Stale instructions are actively harmful
23	Typography token examples (CareHubTypography.bodyLarge)	DELETE	Wrong — actual type is CareHubTypographyTextStyles with different property names
24	Spacing/CornerRadius token examples	SHARPEN	Some examples use wrong names (Spacing.md vs Spacing.sysSpacingMd100). Fix or tell agent to read source files
25	Figma 5-step workflow	DELETE from here	Duplicated in Figma UI Implementation template (doc #12). Keep it there only
26	Agent Boundaries section	KEEP	Non-obvious, specific permission model. Can't be discovered from code
27	Technical Decisions & Rationale	DELETE	"Why Kotlin Multiplatform" doesn't help an agent write code
28	Deployment & Distribution section	DELETE	Discoverable from build configs and CI workflows
29	Known Limitations section	DELETE	Generic KMP limitations ("iOS requires macOS and Xcode") — not project-specific

Verdict: ~70% of this document should be deleted. It's a classic "Overview Trap" + "Kitchen Sink" anti-pattern.

---

2. Project Structure

#	Instruction	Verdict	Reasoning
1	Full directory tree	DELETE	ls exists. Also severely stale (lists 3 feature modules, actual has 14)
2	.spec-workflow/ description	DELETE	Directory structure is discoverable. Also references steering/, templates/, user-templates/, approvals/ subdirs that don't exist
3	File naming conventions (PascalCase, [Feature]ViewModel.kt, etc.)	SHARPEN	Partially discoverable from existing files, but the explicit rule is useful. Remove the obvious ones (PascalCase for Kotlin files — that's the language default)
4	Code naming conventions (classes, functions, constants)	DELETE	These are Kotlin language defaults. PascalCase for classes, camelCase for functions — every Kotlin developer knows this
5	Package naming (com.samsung.carehub)	DELETE	Discoverable from any source file
6	Module Dependency Hierarchy	SHARPEN	The hierarchy itself is discoverable from build.gradle.kts files, but the ownership labels (SRA-owned vs Whisk/SF-owned) are not discoverable and are valuable
7	Team Responsibilities & Module Ownership	KEEP	Critical non-discoverable info about who owns what
8	Feature Module Rules	KEEP	"Features MUST NOT depend on :core:database, :core:network directly" — non-obvious constraint
9	Build Error Prevention Rules	KEEP	Resource import pattern (remove com.samsung. prefix) causes real build failures. Non-obvious
10	Code Size Guidelines (500 lines/file, 300 lines/ViewModel)	KEEP	Not enforced by tooling, specific targets
11	Internationalization rules	KEEP	"PROHIBITED: Placing composeResources at module root level" — non-obvious

Verdict: ~40% should be deleted. Strongest content is ownership boundaries and build error prevention.

---

3. SDD Rules & Guidelines

#	Instruction	Verdict	Reasoning
1	"ALWAYS make sure everything compiles and all tests pass"	DELETE	Generic. Every project expects this
2	"NEVER modify or delete a completed task"	KEEP	Non-obvious process rule
3	Specification Adherence (no convenience methods, no assumptions)	SHARPEN	Good intent but vague. "NO convenience methods" — what counts? Needs examples
4	Technical Refactoring section	KEEP	Non-obvious — replace user stories with technical objectives for refactors
5	After Each File Edit (detekt, ktlintFormat, test, assembleDebug)	KEEP	Specific commands in specific order. Not discoverable from README alone
6	Workflow Decision Tree summary	DELETE	Duplicated from Workflow Decision Tree doc (#11) and Spec Workflow Guide (#1)
7	Working with Ideas	DELETE	"When asked to implement an idea, MUST follow spec-workflow" — this is the entire point of the SDD skill, doesn't need restating
8	Git Workflow (always git add)	DELETE	Standard git practice. "Ignore git add if file is gitignored" — git already does this

Verdict: ~50% should be deleted.

---

4. Specification Creation Requirements

#	Instruction	Verdict	Reasoning
1	"ALL specifications MUST reference steering documents"	KEEP	Process rule, not discoverable
2	Pre-Specification Requirements (read all steering docs)	DELETE	This is already in the Spec Workflow Guide Phase 1. Redundant
3	Task Creation Template with _Prompt	DELETE	Duplicated from Tasks Document Template (#10)
4	Figma MCP Workflow section	DELETE	Duplicated from Figma UI Implementation (#12) — this is the 3rd copy
5	NO HARDCODED VALUES Rule	DELETE from here	Duplicated from Technology Stack. Keep in one place
6	Integration Requirements by Type	SHARPEN	The mapping (ViewModel tasks → tech.md ViewModel constraints) is useful but could be a simple reference table
7	Enforcement & Code Review section	DELETE	Repeats "reject MaterialTheme", "reject hardcoded values" — 4th time across docs
8	"Violation Prevention" paragraph	DELETE	"This must never happen again" — emotional, not actionable

Verdict: ~75% should be deleted. This document is almost entirely redundant with other docs.

---

5. Product Vision

Verdict	Reasoning
KEEP as-is	This is product context, not instructions. Agent references it for requirements alignment. Not discoverable from code. Appropriate as a Notion reference doc

---

6. Workflow Decision Tree

#	Instruction	Verdict	Reasoning
1	Primary decision tree	DELETE	Duplicated in Spec Workflow Guide (which is the actual skill that uses it)
2	Anti-Patterns section	KEEP	Concrete "don't create ViewModel for simple UI component" examples are useful

Verdict: Merge anti-patterns into Spec Workflow Guide, delete this as standalone doc.

---

7-10. Templates (Requirements, Design, Tasks, Implementation Log)

Templates are a different category — they're fill-in-the-blank structures, not steering instructions.

Verdict	Reasoning
KEEP with fixes	Templates serve their purpose. But fix stale references: NavigationHelper → Router, wrong color/typography token names in examples

---

11. Figma UI Implementation

#	Instruction	Verdict	Reasoning
1	5-step workflow	KEEP	This is the authoritative source. Delete copies elsewhere
2	Design Token Quick Reference	SHARPEN	Color names are wrong (CareHubColors.white → CareHubColors.neutralWhite). Either fix to match actual codebase or replace with "Read Color.kt first"
3	Common Pitfalls	KEEP	Specific, actionable

---

12. ViewModel Patterns

#	Instruction	Verdict	Reasoning
1	Standard ViewModel Pattern code	KEEP	Shows exact delegation syntax. Not easily discoverable without reading multiple files
2	Injectable State Pattern	KEEP	Testing pattern, non-obvious
3	Navigation Integration Pattern	SHARPEN	References Navigator — actual is Router. Fix
4	Koin Registration example	SHARPEN	Uses viewModel { } without explicit type — contradicts DI Patterns doc rule. Fix to viewModel<ExampleViewModel> { }
5	Best Practices Do/Don't	DELETE	Generic ("Don't mutate state directly", "Don't block UI thread"). Kotlin coroutines + immutable data classes already enforce this

---

13. UseCase Patterns

#	Instruction	Verdict	Reasoning
1	Single UseCase Pattern	KEEP	Shows operator fun invoke() convention
2	Injection Decision Tree (1-5, 6-10, 10+)	KEEP	Non-obvious architectural decision
3	Complex UseCase Coordination	KEEP	Useful reference
4	Repository Integration note	KEEP	"DON'T create new repositories — use SRA-provided" — critical team boundary
5	Koin Registration	DELETE	Duplicated from DI Patterns doc
6	Best Practices Do/Don't	SHARPEN	Some are specific ("Don't inject more than 5 without facade"), others generic ("Keep focused on single responsibility")

---

14. DI Patterns (Koin)

#	Instruction	Verdict	Reasoning
1	Koin vs Dagger/HILT comparison	DELETE	The project uses Koin. Agent doesn't need to know what Dagger does
2	Explicit type parameter rule	KEEP	Critical, causes runtime crashes if violated
3	Simple/Complex DI patterns	DELETE from here	Already covered in UseCase Patterns (#13) with the injection decision tree
4	Scope Management	KEEP	When to use factory vs single vs viewModel — non-obvious
5	Module Organization	DELETE	Discoverable from existing module files
6	Testing with Koin	KEEP	Shows stopKoin() before startKoin() pattern
7	Decision Tree	DELETE	3rd copy of the injection count decision tree

---

15. KMP Module Structure

#	Instruction	Verdict	Reasoning
1	Directory structure	DELETE	Discoverable from any existing feature module
2	Resource Placement Rules	KEEP	"Android resources in commonMain → will fail on iOS build" — non-obvious
3	Import-to-Dependency Mapping rule	KEEP	Prevents real build errors
4	Resource Import Package Verification	KEEP	com.samsung. prefix removal — critical, non-obvious (but duplicated in Project Structure doc #4)
5	build.gradle.kts Template	SHARPEN	Useful but hardcodes jvmTarget = "17" and specific dependency list. Better to say "copy from existing feature module"
6	Platform-Specific Implementation	DELETE	Generic expect/actual example. Discoverable from existing code
7	Module Registration	DELETE	"Add to settings.gradle.kts" — obvious

---

16. Gradle Dependency Management

#	Instruction	Verdict	Reasoning
1	Version Catalog Required rule	DELETE from here	Already in Technology Stack (which we're keeping)
2	Step-by-step process	DELETE	"Add to version catalog FIRST, then reference in build files" — this is how version catalogs work
3	Version Catalog Structure example	DELETE	Discoverable by reading libs.versions.toml
4	BOM Pattern for Koin	DELETE from here	Already in Technology Stack
5	Source Set Dependency Style	KEEP	"Prefer dot notation over block notation" — non-obvious convention
6	Plugin Exceptions	KEEP	Built-in plugins without version catalog — prevents real errors
7	Common Pitfalls	DELETE	Repeats rules from above

Verdict: ~70% should be deleted. Most is either discoverable or duplicated.

---

17. Test Writing Standards

#	Instruction	Verdict	Reasoning
1	Principles	KEEP	"Write minimal tests during development" — non-obvious, prevents over-testing
2	Naming Conventions	KEEP	Backtick for unit tests, snake_case for UI tests — specific convention
3	Test Structure (AAA)	DELETE	Generic testing practice
4	ViewModel Tests with Turbine example	KEEP	Shows exact pattern
5	Mandatory Rules (1-7)	KEEP	Specific, actionable, not enforced by tooling
6	Forbidden Libraries table	KEEP	Excellent — exact "use X instead of Y"
7	Forbidden Patterns table	KEEP	Detection rules are specific and actionable
8	Test Isolation rules	KEEP	stopKoin() before startKoin() — non-obvious
9	Flaky Test Policy	KEEP	Specific process

Verdict: ~90% is good. This is the best-written steering doc in the set.

---

18. Testing Contract Template

Verdict	Reasoning
KEEP as-is	Template with clear layer definitions, examples, and CI/CD integration. Well-structured

---

Cross-Cutting Findings

CRITICAL: Stale/Incorrect Information

#	Document	Issue	Severity
S1	Spec Workflow Guide, ViewModel Patterns	References NavigationHelper — actual codebase uses Router interface (core/navigation/.../Router.kt)	HIGH — agent will create code importing a nonexistent class
S2	Technology Stack	States Kotlin 2.2.20 — actual is 2.2.21	LOW
S3	Technology Stack	States Compose Multiplatform 1.9.0 — actual is 1.10.1	MEDIUM — significant version jump
S4	Technology Stack	States Ktor 3.3.0 — actual is 3.3.2	LOW
S5	Technology Stack	States Room 2.8.0 — actual is 2.8.4	LOW
S6	Technology Stack	Color examples say CareHubColors.white, CareHubColors.primary — actual names are CareHubColors.neutralWhite, CareHubColors.textNeutralPrimary, CareHubColors.bgNeutralPrimary, etc.	HIGH — compilation errors
S7	Figma UI Implementation	Color quick reference says CareHubColors.white, CareHubColors.blueXlight — actual naming uses semantic prefixes	HIGH — same as S6
S8	Technology Stack	Typography says CareHubTypography.bodyLarge — actual is CareHubTypographyTextStyles with different property names	HIGH — wrong type names
S9	Technology Stack, Tasks Template	Claims ChCard and ChTextField exist — not found in codebase	MEDIUM — nonexistent components
S10	Spec Workflow Guide	References clickup_find_member_by_name — zero ClickUp references in codebase	MEDIUM — dead process step
S11	Project Structure	Lists 3 feature modules — actual has 14	MEDIUM — severely outdated
S12	Multiple docs	References .spec-workflow/steering/*.md — files don't exist	HIGH — agent reads nonexistent files

Redundancy Map

Content repeated across multiple documents (should exist in exactly ONE place):

Rule/Content	Appears In	Should Live In
5-step Figma workflow	Tech Stack, Spec Workflow Guide, Spec Creation Reqs, Tasks Template	Figma UI Implementation only
"No MaterialTheme"	Tech Stack, Figma UI Impl, Tasks Template, Spec Creation Reqs, Spec Workflow Guide, SDD Rules	Tech Stack only
Design token reference	Tech Stack, Figma UI Implementation	Figma UI Implementation only
Post-edit checks (detekt, ktlintFormat, test, assembleDebug)	SDD Rules, Spec Workflow Guide	SDD Rules only
Feature type classification	Workflow Decision Tree, Spec Workflow Guide	Spec Workflow Guide only
ViewModel constraints	Tech Stack, Project Structure	Tech Stack only
Facade pattern (6-10 deps)	UseCase Patterns, DI Patterns	UseCase Patterns only
Version catalog mandatory	Tech Stack, Gradle Dependency Management	Tech Stack only
Koin BOM mandatory	Tech Stack, Gradle Dependency Management	Tech Stack only
Resource import prefix rule	Project Structure, KMP Module Structure	Project Structure only

Contradictions

#	Doc A says	Doc B says	Resolution
C1	Tech Stack: CornerRadius.medium	Figma UI Impl: CornerRadius.sysRadiusMd	Figma doc correct per codebase
C2	ViewModel Patterns: viewModel { } (no explicit type)	DI Patterns: "ALWAYS viewModel<T>{}"	DI Patterns correct — fix ViewModel Patterns
C3	Tech Stack: CareHubColors.primary	Codebase: CareHubColors.bgNeutralPrimary	Codebase wins — fix Tech Stack

---

Recommended Target State

What should exist locally (CLAUDE.md)

A minimal CLAUDE.md at repo root with only non-discoverable hard constraints:

# Build
Post-edit checks: `./gradlew detekt && ./gradlew ktlintFormat && ./gradlew test && ./gradlew assembleDebug`

# Hard Constraints
- All dependencies via version catalog (`libs.versions.toml`). No hardcoded versions.
- Koin BOM required before Koin deps. Explicit types always: `viewModel<T>{}`, `factory<T>{}`, `single<T>{}`.
- No MaterialTheme. Use CareHubTheme only — read design system source files for actual token names.
- ViewModel public API: only action methods + StateFlow (Stateful<T>) + SideEffects. No data properties/getters.
- Features must not depend on :core:database, :core:network, :core:datastore directly.
- Resource imports: strip `com.samsung.` prefix from namespace.
- All user-visible strings via `stringResource(Res.string.*)`.
- Navigation via `Router` interface, not direct navigation.

# Module Ownership
- SRA: core/analytics, core/common, core/data, core/database, core/model, core/network, core/rdfox, core/samsunghealth
- Whisk/SF: core/domain, core/presentation, core/designsystem, core/ui, feature/*
- Modify SRA modules or shared modules (core/*) only after asking.

# Testing
- Mokkery for mocking (not MockK/Mockito). Turbine for StateFlow. kotlin.test assertions (not JUnit/Truth).
- `onNodeWithTag` for UI test interactions. `stopKoin()` before `startKoin()` in test setup.

# SDD Workflow
For feature development, use `/sdd` command. Full process docs in Notion: CareHub > SDD Process.

What should stay in Notion (reduced)

After deduplication, the Notion steering surface should be:

1. Spec Workflow Guide — skill definition (remove ClickUp refs, fix Router, remove duplicated rules)
2. Product Vision — keep as-is
3. Technology Stack — cut to ~30% (remove discoverable info, version numbers, duplicated rules)
4. Project Structure — cut to ownership + build error prevention only
5. Test Writing Standards — keep ~90%
6. Templates (Requirements, Design, Tasks, Testing Contract, Implementation Log, Figma UI Impl) — keep, fix stale references
7. Pattern docs (ViewModel, UseCase, DI) — keep code examples, remove duplicated rules and generic advice

Delete entirely:

• Specification Creation Requirements (~75% redundant)
• Workflow Decision Tree (merged into Spec Workflow Guide)
• Gradle Dependency Management (~70% redundant with Tech Stack + discoverable)
• SDD Rules & Guidelines (merge the 2-3 useful rules into Spec Workflow Guide)

---

Priority Actions

1. Fix stale token names (S6-S8, C1, C3) — HIGH. These cause immediate compilation failures
2. Fix NavigationHelper → Router (S1) — HIGH. Nonexistent class
3. Remove ClickUp refs (S10) — MEDIUM. Dead process step
4. Fix/remove local steering file refs (S12) — HIGH. Nonexistent files
5. Create local CLAUDE.md — HIGH. Eliminates 19 Notion fetches for routine tasks
6. Deduplicate — MEDIUM. 5-step Figma workflow in 1 place, MaterialTheme rule in 1 place
7. Delete discoverable info — LOW. Reduces token cost ~20% per SDD run
8. Fix ViewModel Patterns Koin example (C2) — MEDIUM. Contradicts explicit type rule
9. Fix ChCard/ChTextField refs (S9) — MEDIUM. Nonexistent components
10. Delete/merge redundant docs — LOW. Spec Creation Reqs, Workflow Decision Tree, Gradle Dependency Mgmt