behavioral-guardrails

---

name: behavioral-guardrails description: Behavioral guidelines for EchoChat tasks: clarify ambiguity, keep changes simple and surgical, and define verifiable success criteria before coding. license: MIT compatibility: all metadata: audience: ai-coding-agents framework: flutter pattern: behavioral-guidelines

Behavioral Guardrails

Use this skill when writing, reviewing, refactoring, or planning code in EchoChat. It adapts the reusable ideas from the Karpathy-inspired claude-skills project to this repo's conventions.

Tradeoff: these guardrails bias toward caution over speed. For trivial one-line fixes, use judgment.

1. Think before coding

Do not silently choose an interpretation when the request is ambiguous.

Before implementing:

• State assumptions when they affect the code shape, generated files, external IDs, or user-visible behavior.
• Ask before changing package IDs, bundle IDs, signing paths, CI/CD, generated workflows, backend API contracts, or broad formatting.
• If multiple implementation paths are plausible, present the main tradeoff briefly.
• Push back when a smaller repo-native approach exists.
• Stop and ask when project patterns conflict or a required source of truth is unclear.

EchoChat examples:

• Rebrand requests need display name vs technical identifier clarification.
• Localization requests need target locales and translation source clarified.
• Chat or auth API changes must keep the Flutter client DTOs, Retrofit declarations, and Dart Frog route contracts aligned.
• New client features should use module-scaffold, bloc-pattern, and route-config rather than ad-hoc Flutter structure.

2. Simplicity first

Write the minimum code that solves the current request.

• No speculative features, flags, adapters, or abstractions.
• No new widget when an existing fl_ui, core, or module widget fits.
• No custom BLoC/state shape; use the repo bloc-pattern.
• No custom localization flow; update CSV and run make lang.
• No direct generated-file edits when a generator exists.
• Keep Dart Frog route handlers thin; put backend business logic in services.

The test: if the same behavior can be expressed with an existing helper or pattern, reuse it.

3. Surgical changes

Every changed line should trace back to the user request or to a required generator output.

When editing:

• Do not reformat unrelated files unless the user asks or the formatter is intentionally part of the task.
• Do not refactor adjacent code while fixing a bug.
• Remove only imports/functions/files made unused by your change.
• Mention unrelated dead code or stale docs instead of deleting them.
• Keep generated output scoped to the package whose source inputs changed when possible.

If a command causes broad churn, pause and ask whether to keep or revert it.

4. Goal-driven execution

Turn each task into a verifiable outcome.

For multi-step work, track:

1. Change source of truth → verify generated/config output
2. Update call sites → verify stale references are gone
3. Run targeted checks → verify analyzer/tests pass

Prefer concrete checks:

• rg for stale identifiers, locale codes, old keys, or API route names.
• make lang after localization CSV edits.
• make gen_core, make gen_data_source, make gen_main, or make gen_all only after relevant generated inputs change.
• fvm flutter analyze --no-pub from affected Flutter packages.
• make test_backend after backend service or route changes.
• UI smoke tests for user-facing flow changes when a device/browser is available.

5. EchoChat source-of-truth rules

Use these before editing derived files:

Area	Source of truth	Regenerate/check
App IDs/display names	apps/main/app_identifier.yaml	sh gen_app_identifier.sh apps/main
App/core/media strings	*/lib/l10n/localizations.csv	make lang
BLoC _StateData / JSON / DI	annotated Dart files	make gen_core, make gen_data_source, make gen_main, or make gen_all
Flutter API client	Retrofit declarations and DTOs in core / modules/data_source	make gen_core / make gen_data_source
Backend API behavior	Dart Frog routes plus services under apps/backend/lib/src/services	make test_backend
Theme tokens	plugins/fl_theme/ and existing extensions	fvm flutter analyze --no-pub
Navigation	IRoute, CustomRouter, coordinators	route-config checklist

Checklist

• Ambiguity clarified before edits.
• Existing repo skill/pattern reused.
• No speculative abstraction or drive-by refactor.
• Generated files updated only via the proper generator.
• Flutter client and backend contracts kept aligned when APIs change.
• Stale references searched after rename/localization/API work.
• Targeted analyzer/tests run or explicitly reported as not run.
• Any broad formatter/generator churn was approved or reverted.

Related

• module-scaffold
• bloc-pattern
• route-config
• localization
• data-layer
• code-generation
• flutter-reviewer