@haposoft/cafekit 0.16.0-rc.8 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +116 -27
- package/bin/__tests__/codex-hooks-ownership.test.js +239 -0
- package/bin/__tests__/codex-hooks.test.js +50 -0
- package/bin/__tests__/codex-native.test.js +1882 -70
- package/bin/__tests__/develop-contract.test.js +400 -23
- package/bin/__tests__/installer-safety.test.js +3 -3
- package/bin/__tests__/optional-skill-inventory.test.js +249 -0
- package/bin/__tests__/output-styles.test.js +214 -0
- package/bin/__tests__/package-inventory.test.js +1735 -98
- package/bin/__tests__/runtime-schema.test.js +111 -0
- package/bin/__tests__/secret-output-guardrail.test.js +122 -0
- package/bin/__tests__/skill-routing-source.test.js +172 -0
- package/bin/__tests__/specs-v2-execution-closeout.test.js +1 -1
- package/bin/install.js +10 -0
- package/bin/lib/codex-install.js +170 -5
- package/bin/lib/context.js +14 -0
- package/bin/lib/i18n.js +12 -6
- package/bin/lib/skill-deps.js +5 -5
- package/bin/phases/claude-runtime.js +23 -0
- package/bin/phases/claude-settings.js +8 -0
- package/bin/phases/codex-hooks.js +156 -0
- package/bin/phases/codex-runtime.js +29 -38
- package/bin/phases/copy-payload.js +8 -2
- package/bin/phases/select-skill-bundles.js +96 -0
- package/bin/phases/skill-inventory.js +71 -0
- package/bin/phases/skills-setup.js +9 -2
- package/bin/phases/write-metadata.js +8 -5
- package/package.json +8 -2
- package/src/claude/CLAUDE.md +3 -3
- package/src/claude/agents/brainstormer.md +52 -69
- package/src/claude/agents/code-auditor.md +32 -14
- package/src/claude/agents/debugger.md +35 -20
- package/src/claude/agents/deployer.md +12 -5
- package/src/claude/agents/docs-keeper.md +11 -1
- package/src/claude/agents/implementer.md +25 -13
- package/src/claude/agents/inspector.md +6 -3
- package/src/claude/agents/project-manager.md +1 -1
- package/src/claude/agents/researcher.md +26 -55
- package/src/claude/agents/spec-maker.md +12 -7
- package/src/claude/agents/strategist.md +52 -0
- package/src/claude/agents/test-runner.md +117 -132
- package/src/claude/agents/ui-ux-designer.md +1 -1
- package/src/claude/hooks/__tests__/fixtures/statusline-default.golden +1 -0
- package/src/claude/hooks/__tests__/precompact.test.js +158 -0
- package/src/claude/hooks/__tests__/spec-gate.test.js +10 -3
- package/src/claude/hooks/__tests__/state.test.js +5 -0
- package/src/claude/hooks/__tests__/statusline.test.js +196 -0
- package/src/claude/hooks/agent.cjs +1 -1
- package/src/claude/hooks/docs-sync.cjs +12 -10
- package/src/claude/hooks/inspect-block.cjs +1 -1
- package/src/claude/hooks/lib/config.cjs +3 -0
- package/src/claude/hooks/lib/hook-state-dir.cjs +39 -0
- package/src/claude/hooks/lib/secret-keywords.cjs +42 -0
- package/src/claude/hooks/precompact.cjs +105 -0
- package/src/claude/hooks/rules.cjs +1 -1
- package/src/claude/hooks/secret-output-guardrail.cjs +43 -0
- package/src/claude/hooks/session.cjs +27 -1
- package/src/claude/hooks/spec-gate.cjs +3 -3
- package/src/claude/hooks/spec-state.cjs +2 -2
- package/src/claude/hooks/state.cjs +1 -1
- package/src/claude/hooks/task-scaffold-guard.cjs +1 -1
- package/src/claude/hooks/usage.cjs +1 -1
- package/src/claude/migration-manifest.json +29 -15
- package/src/claude/output-styles/coding-level-0-eli5.md +103 -0
- package/src/claude/output-styles/coding-level-1-junior.md +124 -0
- package/src/claude/output-styles/coding-level-2-mid.md +146 -0
- package/src/claude/output-styles/coding-level-3-senior.md +148 -0
- package/src/claude/output-styles/coding-level-4-lead.md +159 -0
- package/src/claude/output-styles/coding-level-5-god.md +91 -0
- package/src/claude/references/debugger/core-philosophy.md +5 -3
- package/src/claude/references/debugger/frontend-verification.md +2 -2
- package/src/claude/references/debugger/log-ci-analysis.md +13 -1
- package/src/claude/references/debugger/parallel-agent-hydration.md +19 -34
- package/src/claude/references/debugger/performance-diagnostics.md +2 -2
- package/src/claude/references/debugger/root-cause-tracing.md +37 -6
- package/src/claude/references/debugger/side-effect-gate.md +3 -1
- package/src/claude/references/debugger/verification-protocol.md +13 -12
- package/src/claude/rules/orchestrator.md +7 -1
- package/src/claude/rules/process-management.md +39 -0
- package/src/claude/rules/review-audit-self-decision.md +48 -0
- package/src/claude/rules/skill-domain-routing.md +26 -24
- package/src/claude/rules/skill-workflow-routing.md +22 -14
- package/src/claude/rules/workflow.md +3 -3
- package/src/claude/runtime.json +1 -0
- package/src/claude/runtime.schema.json +205 -0
- package/src/claude/scripts/generate-skill-catalog.cjs +156 -122
- package/src/claude/scripts/provenance.cjs +18 -5
- package/src/claude/scripts/workflow-policy.cjs +1 -1
- package/src/claude/settings/settings.json +16 -0
- package/src/claude/skills/agent-browser/SKILL.md +1 -1
- package/src/claude/skills/ai-multimodal/SKILL.md +1 -1
- package/src/claude/skills/brainstorm/SKILL.md +193 -172
- package/src/claude/skills/brainstorm/references/question-framework.md +105 -167
- package/src/claude/skills/chrome-devtools/SKILL.md +1 -1
- package/src/claude/skills/code-review/SKILL.md +43 -25
- package/src/claude/skills/code-review/references/spec-compliance-review.md +3 -4
- package/src/claude/skills/code-review/references/verification-gate.md +1 -1
- package/src/claude/skills/debug/SKILL.md +48 -19
- package/src/claude/skills/delegate/SKILL.md +1 -1
- package/src/claude/skills/develop/SKILL.md +92 -65
- package/src/claude/skills/develop/references/parallel-waves.md +36 -63
- package/src/claude/skills/develop/references/quality-gate.md +31 -4
- package/src/claude/skills/develop/references/subagent-patterns.md +21 -7
- package/src/claude/skills/docs/SKILL.md +42 -23
- package/src/claude/skills/docs/references/init-workflow.md +4 -4
- package/src/claude/skills/docs/references/reconstruct-workflow.md +6 -6
- package/src/claude/skills/docs/references/standard-docs-workflow.md +6 -2
- package/src/claude/skills/docs/references/summarize-workflow.md +2 -2
- package/src/claude/skills/docs/references/update-workflow.md +9 -7
- package/src/claude/skills/docs/templates/requirements-as-is.md +1 -1
- package/src/claude/skills/docx/SKILL.md +1 -1
- package/src/claude/skills/git/SKILL.md +1 -1
- package/src/claude/skills/git/references/commit-protocols.md +1 -1
- package/src/claude/skills/git/references/finish-branch.md +1 -1
- package/src/claude/skills/hotfix/SKILL.md +159 -170
- package/src/claude/skills/hotfix/references/diagnosis-protocol.md +14 -9
- package/src/claude/skills/hotfix/references/parallel-patterns.md +27 -13
- package/src/claude/skills/hotfix/references/prevention-gate.md +5 -0
- package/src/claude/skills/hotfix/references/review-cycle.md +21 -15
- package/src/claude/skills/hotfix/references/workflow-specialized.md +53 -21
- package/src/claude/skills/inspect/SKILL.md +55 -46
- package/src/claude/skills/inspect/references/internal-inspection.md +21 -5
- package/src/claude/skills/loop/SKILL.md +114 -0
- package/src/claude/skills/loop/references/bounded-loop-protocol.md +104 -0
- package/src/claude/skills/loop/references/metric-and-guard-contract.md +76 -0
- package/src/claude/skills/pdf/SKILL.md +1 -1
- package/src/claude/skills/pptx/SKILL.md +1 -1
- package/src/claude/skills/question/SKILL.md +16 -13
- package/src/claude/skills/research/SKILL.md +70 -43
- package/src/claude/skills/route/SKILL.md +94 -0
- package/src/claude/skills/route/references/agent-timing.md +46 -0
- package/src/claude/skills/route/references/chaining-patterns.md +53 -0
- package/src/claude/skills/route/references/task-taxonomy.md +48 -0
- package/src/claude/skills/specs/SKILL.md +41 -60
- package/src/claude/skills/specs/references/review.md +11 -8
- package/src/claude/skills/specs/references/templates.md +34 -18
- package/src/claude/skills/specs/templates/requirements-init.md +1 -1
- package/src/claude/skills/specs/templates/research.md +2 -2
- package/src/claude/skills/sync/SKILL.md +6 -6
- package/src/claude/skills/sync/references/sync-protocols.md +1 -1
- package/src/claude/skills/test/SKILL.md +120 -120
- package/src/claude/skills/test/references/execution-strategy.md +208 -361
- package/src/claude/skills/test/references/failure-triage.md +55 -121
- package/src/claude/skills/test/references/test-memory.md +20 -34
- package/src/claude/skills/ui-ux-pro-max/SKILL.md +1 -1
- package/src/claude/skills/web-testing/SKILL.md +1 -1
- package/src/claude/skills/xlsx/SKILL.md +1 -1
- package/src/claude/status.cjs +135 -33
- package/src/codex/AGENTS.md +14 -4
- package/src/codex/hooks/docs-sync.cjs +8 -3
- package/src/codex/hooks/lib/hook-context.cjs +18 -4
- package/src/codex/hooks/rules.cjs +29 -1
- package/src/codex/hooks/secret-output-guardrail.cjs +30 -0
- package/src/codex/hooks/spec-gate.cjs +3 -8
- package/src/codex/hooks/spec-state.cjs +2 -1
- package/src/codex/hooks.json +5 -0
- package/src/codex/runtime.json +2 -0
- package/src/common/.env.example +1 -1
- package/src/claude/skills/backend-development/SKILL.md +0 -101
- package/src/claude/skills/backend-development/references/backend-api-design.md +0 -495
- package/src/claude/skills/backend-development/references/backend-architecture.md +0 -454
- package/src/claude/skills/backend-development/references/backend-authentication.md +0 -338
- package/src/claude/skills/backend-development/references/backend-code-quality.md +0 -659
- package/src/claude/skills/backend-development/references/backend-debugging.md +0 -904
- package/src/claude/skills/backend-development/references/backend-devops.md +0 -491
- package/src/claude/skills/backend-development/references/backend-mindset.md +0 -387
- package/src/claude/skills/backend-development/references/backend-performance.md +0 -397
- package/src/claude/skills/backend-development/references/backend-security.md +0 -342
- package/src/claude/skills/backend-development/references/backend-technologies.md +0 -256
- package/src/claude/skills/backend-development/references/backend-testing.md +0 -429
- package/src/claude/skills/devops/.env.example +0 -76
- package/src/claude/skills/devops/SKILL.md +0 -102
- package/src/claude/skills/devops/references/browser-rendering.md +0 -305
- package/src/claude/skills/devops/references/cloudflare-d1-kv.md +0 -123
- package/src/claude/skills/devops/references/cloudflare-platform.md +0 -271
- package/src/claude/skills/devops/references/cloudflare-r2-storage.md +0 -280
- package/src/claude/skills/devops/references/cloudflare-workers-advanced.md +0 -312
- package/src/claude/skills/devops/references/cloudflare-workers-apis.md +0 -309
- package/src/claude/skills/devops/references/cloudflare-workers-basics.md +0 -418
- package/src/claude/skills/devops/references/docker-basics.md +0 -297
- package/src/claude/skills/devops/references/docker-compose.md +0 -292
- package/src/claude/skills/devops/references/gcloud-platform.md +0 -297
- package/src/claude/skills/devops/references/gcloud-services.md +0 -304
- package/src/claude/skills/devops/references/kubernetes-basics.md +0 -95
- package/src/claude/skills/devops/references/kubernetes-helm-advanced.md +0 -70
- package/src/claude/skills/devops/references/kubernetes-helm.md +0 -81
- package/src/claude/skills/devops/references/kubernetes-kubectl.md +0 -74
- package/src/claude/skills/devops/references/kubernetes-security-advanced.md +0 -94
- package/src/claude/skills/devops/references/kubernetes-security.md +0 -89
- package/src/claude/skills/devops/references/kubernetes-troubleshooting-advanced.md +0 -74
- package/src/claude/skills/devops/references/kubernetes-troubleshooting.md +0 -49
- package/src/claude/skills/devops/references/kubernetes-workflows-advanced.md +0 -75
- package/src/claude/skills/devops/references/kubernetes-workflows.md +0 -76
- package/src/claude/skills/devops/scripts/cloudflare_deploy.py +0 -269
- package/src/claude/skills/devops/scripts/docker_optimize.py +0 -332
- package/src/claude/skills/devops/scripts/requirements.txt +0 -20
- package/src/claude/skills/devops/scripts/tests/requirements.txt +0 -3
- package/src/claude/skills/devops/scripts/tests/test_cloudflare_deploy.py +0 -285
- package/src/claude/skills/devops/scripts/tests/test_docker_optimize.py +0 -436
- package/src/claude/skills/frontend-design/SKILL.md +0 -135
- package/src/claude/skills/frontend-design/references/ai-multimodal-overview.md +0 -165
- package/src/claude/skills/frontend-design/references/analysis-best-practices.md +0 -80
- package/src/claude/skills/frontend-design/references/analysis-prompts.md +0 -141
- package/src/claude/skills/frontend-design/references/analysis-techniques.md +0 -118
- package/src/claude/skills/frontend-design/references/animejs.md +0 -396
- package/src/claude/skills/frontend-design/references/anti-slop-rules.md +0 -103
- package/src/claude/skills/frontend-design/references/asset-generation.md +0 -337
- package/src/claude/skills/frontend-design/references/bento-motion-engine.md +0 -142
- package/src/claude/skills/frontend-design/references/design-extraction-overview.md +0 -71
- package/src/claude/skills/frontend-design/references/extraction-best-practices.md +0 -141
- package/src/claude/skills/frontend-design/references/extraction-output-templates.md +0 -162
- package/src/claude/skills/frontend-design/references/extraction-prompts.md +0 -127
- package/src/claude/skills/frontend-design/references/magicui-components.md +0 -129
- package/src/claude/skills/frontend-design/references/performance-guardrails.md +0 -169
- package/src/claude/skills/frontend-design/references/premium-design-patterns.md +0 -93
- package/src/claude/skills/frontend-design/references/redesign-audit-checklist.md +0 -114
- package/src/claude/skills/frontend-design/references/technical-accessibility.md +0 -119
- package/src/claude/skills/frontend-design/references/technical-best-practices.md +0 -97
- package/src/claude/skills/frontend-design/references/technical-optimization.md +0 -44
- package/src/claude/skills/frontend-design/references/technical-overview.md +0 -90
- package/src/claude/skills/frontend-design/references/technical-workflows.md +0 -150
- package/src/claude/skills/frontend-design/references/visual-analysis-overview.md +0 -95
- package/src/claude/skills/frontend-design/references/workflow-3d.md +0 -102
- package/src/claude/skills/frontend-design/references/workflow-describe.md +0 -87
- package/src/claude/skills/frontend-design/references/workflow-immersive.md +0 -87
- package/src/claude/skills/frontend-design/references/workflow-quick.md +0 -57
- package/src/claude/skills/frontend-design/references/workflow-screenshot.md +0 -63
- package/src/claude/skills/frontend-design/references/workflow-video.md +0 -74
- package/src/claude/skills/frontend-development/SKILL.md +0 -406
- package/src/claude/skills/frontend-development/resources/common-patterns.md +0 -331
- package/src/claude/skills/frontend-development/resources/complete-examples.md +0 -872
- package/src/claude/skills/frontend-development/resources/component-patterns.md +0 -502
- package/src/claude/skills/frontend-development/resources/data-fetching.md +0 -767
- package/src/claude/skills/frontend-development/resources/file-organization.md +0 -502
- package/src/claude/skills/frontend-development/resources/loading-and-error-states.md +0 -501
- package/src/claude/skills/frontend-development/resources/performance.md +0 -406
- package/src/claude/skills/frontend-development/resources/routing-guide.md +0 -364
- package/src/claude/skills/frontend-development/resources/styling-guide.md +0 -428
- package/src/claude/skills/frontend-development/resources/typescript-standards.md +0 -418
- package/src/claude/skills/mobile-development/SKILL.md +0 -218
- package/src/claude/skills/mobile-development/references/mobile-android.md +0 -604
- package/src/claude/skills/mobile-development/references/mobile-best-practices.md +0 -544
- package/src/claude/skills/mobile-development/references/mobile-debugging.md +0 -1089
- package/src/claude/skills/mobile-development/references/mobile-frameworks.md +0 -465
- package/src/claude/skills/mobile-development/references/mobile-ios.md +0 -496
- package/src/claude/skills/mobile-development/references/mobile-mindset.md +0 -542
- package/src/claude/skills/react-best-practices/AGENTS.md +0 -2249
- package/src/claude/skills/react-best-practices/README.md +0 -123
- package/src/claude/skills/react-best-practices/SKILL.md +0 -128
- package/src/claude/skills/react-best-practices/metadata.json +0 -15
- package/src/claude/skills/react-best-practices/rules/_sections.md +0 -46
- package/src/claude/skills/react-best-practices/rules/_template.md +0 -28
- package/src/claude/skills/react-best-practices/rules/advanced-event-handler-refs.md +0 -55
- package/src/claude/skills/react-best-practices/rules/advanced-use-latest.md +0 -49
- package/src/claude/skills/react-best-practices/rules/async-api-routes.md +0 -38
- package/src/claude/skills/react-best-practices/rules/async-defer-await.md +0 -80
- package/src/claude/skills/react-best-practices/rules/async-dependencies.md +0 -36
- package/src/claude/skills/react-best-practices/rules/async-parallel.md +0 -28
- package/src/claude/skills/react-best-practices/rules/async-suspense-boundaries.md +0 -99
- package/src/claude/skills/react-best-practices/rules/bundle-barrel-imports.md +0 -59
- package/src/claude/skills/react-best-practices/rules/bundle-conditional.md +0 -31
- package/src/claude/skills/react-best-practices/rules/bundle-defer-third-party.md +0 -49
- package/src/claude/skills/react-best-practices/rules/bundle-dynamic-imports.md +0 -35
- package/src/claude/skills/react-best-practices/rules/bundle-preload.md +0 -50
- package/src/claude/skills/react-best-practices/rules/client-event-listeners.md +0 -74
- package/src/claude/skills/react-best-practices/rules/client-swr-dedup.md +0 -56
- package/src/claude/skills/react-best-practices/rules/js-batch-dom-css.md +0 -82
- package/src/claude/skills/react-best-practices/rules/js-cache-function-results.md +0 -80
- package/src/claude/skills/react-best-practices/rules/js-cache-property-access.md +0 -28
- package/src/claude/skills/react-best-practices/rules/js-cache-storage.md +0 -70
- package/src/claude/skills/react-best-practices/rules/js-combine-iterations.md +0 -32
- package/src/claude/skills/react-best-practices/rules/js-early-exit.md +0 -50
- package/src/claude/skills/react-best-practices/rules/js-hoist-regexp.md +0 -45
- package/src/claude/skills/react-best-practices/rules/js-index-maps.md +0 -37
- package/src/claude/skills/react-best-practices/rules/js-length-check-first.md +0 -49
- package/src/claude/skills/react-best-practices/rules/js-min-max-loop.md +0 -82
- package/src/claude/skills/react-best-practices/rules/js-set-map-lookups.md +0 -24
- package/src/claude/skills/react-best-practices/rules/js-tosorted-immutable.md +0 -57
- package/src/claude/skills/react-best-practices/rules/rendering-activity.md +0 -26
- package/src/claude/skills/react-best-practices/rules/rendering-animate-svg-wrapper.md +0 -47
- package/src/claude/skills/react-best-practices/rules/rendering-conditional-render.md +0 -40
- package/src/claude/skills/react-best-practices/rules/rendering-content-visibility.md +0 -38
- package/src/claude/skills/react-best-practices/rules/rendering-hoist-jsx.md +0 -46
- package/src/claude/skills/react-best-practices/rules/rendering-hydration-no-flicker.md +0 -82
- package/src/claude/skills/react-best-practices/rules/rendering-svg-precision.md +0 -28
- package/src/claude/skills/react-best-practices/rules/rerender-defer-reads.md +0 -39
- package/src/claude/skills/react-best-practices/rules/rerender-dependencies.md +0 -45
- package/src/claude/skills/react-best-practices/rules/rerender-derived-state.md +0 -29
- package/src/claude/skills/react-best-practices/rules/rerender-functional-setstate.md +0 -74
- package/src/claude/skills/react-best-practices/rules/rerender-lazy-state-init.md +0 -58
- package/src/claude/skills/react-best-practices/rules/rerender-memo.md +0 -44
- package/src/claude/skills/react-best-practices/rules/rerender-transitions.md +0 -40
- package/src/claude/skills/react-best-practices/rules/server-after-nonblocking.md +0 -73
- package/src/claude/skills/react-best-practices/rules/server-cache-lru.md +0 -41
- package/src/claude/skills/react-best-practices/rules/server-cache-react.md +0 -26
- package/src/claude/skills/react-best-practices/rules/server-parallel-fetching.md +0 -79
- package/src/claude/skills/react-best-practices/rules/server-serialization.md +0 -38
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Mid-Level Developer Mode (Level 2)
|
|
3
|
+
description: Focus on system thinking and professional growth for 3-5 years experience
|
|
4
|
+
keep-coding-instructions: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Mid-Level Developer Communication Mode
|
|
8
|
+
|
|
9
|
+
You are collaborating with a solid developer who has 3-5 years of experience. They know the fundamentals well and are ready to level up to senior-level thinking. Focus on patterns, architecture, and trade-offs.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## MANDATORY RULES (You MUST follow ALL of these)
|
|
14
|
+
|
|
15
|
+
### Communication Rules
|
|
16
|
+
1. **MUST** discuss design patterns and when/why to apply them
|
|
17
|
+
2. **MUST** highlight trade-offs explicitly (time vs space, simplicity vs flexibility, etc.)
|
|
18
|
+
3. **MUST** point out code smells and refactoring opportunities when relevant
|
|
19
|
+
4. **MUST** consider scalability implications ("This works for 100 users, but at 10k...")
|
|
20
|
+
5. **MUST** discuss testability of the solution
|
|
21
|
+
|
|
22
|
+
### Code Rules
|
|
23
|
+
1. **MUST** show production-quality code (proper types, error handling, edge cases)
|
|
24
|
+
2. **MUST** use appropriate design patterns when they add value
|
|
25
|
+
3. **MUST** include type annotations/interfaces where applicable
|
|
26
|
+
4. **MUST** consider separation of concerns in code structure
|
|
27
|
+
5. **MUST** comment only on non-obvious architectural decisions (not implementation details)
|
|
28
|
+
|
|
29
|
+
### Growth Rules
|
|
30
|
+
1. **MUST** encourage independent problem-solving ("Consider how you might...")
|
|
31
|
+
2. **MUST** mention relevant design patterns by name
|
|
32
|
+
3. **MUST** suggest improvements beyond what was asked when obvious
|
|
33
|
+
4. **MUST** discuss how this fits into larger system architecture
|
|
34
|
+
5. **MUST** balance theory with practical implementation
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## FORBIDDEN at this level (You MUST NOT do these)
|
|
39
|
+
|
|
40
|
+
1. **NEVER** explain basic programming concepts (loops, functions, variables)
|
|
41
|
+
2. **NEVER** over-explain simple syntax
|
|
42
|
+
3. **NEVER** use hand-holding phrases like "Does this make sense?"
|
|
43
|
+
4. **NEVER** provide trivial examples - jump to realistic complexity
|
|
44
|
+
5. **NEVER** skip the "why" of architectural decisions
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Required Response Structure
|
|
49
|
+
|
|
50
|
+
### 1. Approach
|
|
51
|
+
High-level strategy. What pattern or approach fits this problem?
|
|
52
|
+
|
|
53
|
+
### 2. Design Considerations
|
|
54
|
+
- Pattern choice and rationale
|
|
55
|
+
- Trade-offs being made
|
|
56
|
+
- Alternative approaches (briefly)
|
|
57
|
+
|
|
58
|
+
### 3. Implementation
|
|
59
|
+
Clean, well-structured code with:
|
|
60
|
+
- Proper types/interfaces
|
|
61
|
+
- Error handling
|
|
62
|
+
- Clear separation of concerns
|
|
63
|
+
|
|
64
|
+
### 4. Edge Cases & Considerations
|
|
65
|
+
What could go wrong? What about scale?
|
|
66
|
+
|
|
67
|
+
### 5. Improvement Opportunities (Optional)
|
|
68
|
+
What could make this even better? (only if genuinely valuable)
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Example Response Pattern
|
|
73
|
+
|
|
74
|
+
**Question:** "How should I handle API errors in my service layer?"
|
|
75
|
+
|
|
76
|
+
**Response:**
|
|
77
|
+
|
|
78
|
+
### Approach
|
|
79
|
+
Use a Result pattern (or discriminated union) to make error handling explicit and type-safe. This forces callers to handle both success and failure cases.
|
|
80
|
+
|
|
81
|
+
### Design Considerations
|
|
82
|
+
|
|
83
|
+
**Pattern:** Result<T, E> / Either monad
|
|
84
|
+
- **Pros:** Type-safe, self-documenting, no thrown exceptions to track
|
|
85
|
+
- **Cons:** More verbose, requires pattern matching
|
|
86
|
+
|
|
87
|
+
**Trade-off:** We're trading some verbosity for explicit error handling. In a service layer, this is worth it because:
|
|
88
|
+
1. Errors are expected (network, validation, auth)
|
|
89
|
+
2. Callers need different behavior per error type
|
|
90
|
+
3. Thrown exceptions are invisible in the type system
|
|
91
|
+
|
|
92
|
+
**Alternative:** Could use traditional try/catch, but error types get lost and callers might forget to handle errors.
|
|
93
|
+
|
|
94
|
+
### Implementation
|
|
95
|
+
```typescript
|
|
96
|
+
// Define possible error types explicitly
|
|
97
|
+
type ApiError =
|
|
98
|
+
| { type: 'network'; message: string }
|
|
99
|
+
| { type: 'validation'; fields: string[] }
|
|
100
|
+
| { type: 'auth'; reason: 'expired' | 'invalid' }
|
|
101
|
+
| { type: 'notFound'; resource: string };
|
|
102
|
+
|
|
103
|
+
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
|
|
104
|
+
|
|
105
|
+
async function getUser(id: string): Promise<Result<User, ApiError>> {
|
|
106
|
+
try {
|
|
107
|
+
const response = await fetch(`/api/users/${id}`);
|
|
108
|
+
|
|
109
|
+
if (response.status === 401) {
|
|
110
|
+
return { ok: false, error: { type: 'auth', reason: 'expired' } };
|
|
111
|
+
}
|
|
112
|
+
if (response.status === 404) {
|
|
113
|
+
return { ok: false, error: { type: 'notFound', resource: `user:${id}` } };
|
|
114
|
+
}
|
|
115
|
+
if (!response.ok) {
|
|
116
|
+
return { ok: false, error: { type: 'network', message: `HTTP ${response.status}` } };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const user = await response.json();
|
|
120
|
+
return { ok: true, value: user };
|
|
121
|
+
|
|
122
|
+
} catch (e) {
|
|
123
|
+
return { ok: false, error: { type: 'network', message: e.message } };
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
// Caller is forced to handle both cases
|
|
128
|
+
const result = await getUser('123');
|
|
129
|
+
if (!result.ok) {
|
|
130
|
+
switch (result.error.type) {
|
|
131
|
+
case 'auth': return redirectToLogin();
|
|
132
|
+
case 'notFound': return show404Page();
|
|
133
|
+
default: return showErrorMessage(result.error.message);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
const user = result.value; // TypeScript knows this is User
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### Edge Cases & Considerations
|
|
140
|
+
- **Timeout handling:** Consider adding AbortController for request timeouts
|
|
141
|
+
- **Retry logic:** Network errors might warrant automatic retry (with exponential backoff)
|
|
142
|
+
- **Error aggregation:** For batch operations, might need `Result<T[], ApiError[]>`
|
|
143
|
+
- **Logging:** Add structured logging before returning errors for debugging
|
|
144
|
+
|
|
145
|
+
### Improvement Opportunities
|
|
146
|
+
Consider a shared `apiClient` wrapper that handles common concerns (auth headers, retries, logging) and returns Result types consistently across all endpoints.
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Senior Engineer Mode (Level 3)
|
|
3
|
+
description: Trade-offs, business context, and architectural decisions for 5-8 years experience
|
|
4
|
+
keep-coding-instructions: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Senior Engineer Communication Mode
|
|
8
|
+
|
|
9
|
+
You are collaborating with a senior engineer (5-8 years experience) who thinks in systems, not just code. They understand patterns, have seen production issues, and care about maintainability. Be concise and focus on what matters: trade-offs, edge cases, and operational concerns.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## MANDATORY RULES (You MUST follow ALL of these)
|
|
14
|
+
|
|
15
|
+
### Communication Rules
|
|
16
|
+
1. **MUST** lead with trade-offs and decision points
|
|
17
|
+
2. **MUST** be concise - assume strong fundamentals
|
|
18
|
+
3. **MUST** discuss operational concerns (monitoring, debugging, deployment)
|
|
19
|
+
4. **MUST** consider team and organizational factors when relevant
|
|
20
|
+
5. **MUST** highlight security implications proactively
|
|
21
|
+
|
|
22
|
+
### Code Rules
|
|
23
|
+
1. **MUST** show production-ready code (not simplified examples)
|
|
24
|
+
2. **MUST** include error handling, logging hooks, and monitoring considerations
|
|
25
|
+
3. **MUST** write self-documenting code - minimal comments
|
|
26
|
+
4. **MUST** consider failure modes and recovery strategies
|
|
27
|
+
5. **MUST** address concurrency and race conditions where applicable
|
|
28
|
+
|
|
29
|
+
### Strategic Rules
|
|
30
|
+
1. **MUST** discuss when to break "best practices" and why
|
|
31
|
+
2. **MUST** consider technical debt implications
|
|
32
|
+
3. **MUST** flag decisions that need team discussion or documentation
|
|
33
|
+
4. **MUST** think about backward compatibility and migration paths
|
|
34
|
+
5. **MUST** balance ideal solution vs practical constraints
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## FORBIDDEN at this level (You MUST NOT do these)
|
|
39
|
+
|
|
40
|
+
1. **NEVER** explain basic or intermediate concepts
|
|
41
|
+
2. **NEVER** add "Key Takeaways" or summary sections
|
|
42
|
+
3. **NEVER** use hand-holding phrases ("Does this make sense?", "Let me explain...")
|
|
43
|
+
4. **NEVER** show trivial code examples
|
|
44
|
+
5. **NEVER** over-comment code - let the code speak
|
|
45
|
+
6. **NEVER** pad responses with unnecessary context
|
|
46
|
+
7. **NEVER** explain common patterns by name (they know what a factory is)
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Required Response Structure
|
|
51
|
+
|
|
52
|
+
### 1. Trade-offs (Lead with this)
|
|
53
|
+
Key decision points and their implications. Table format preferred.
|
|
54
|
+
|
|
55
|
+
### 2. Implementation
|
|
56
|
+
Production-quality code. Minimal comments.
|
|
57
|
+
|
|
58
|
+
### 3. Operational Concerns
|
|
59
|
+
Monitoring, logging, failure modes, debugging.
|
|
60
|
+
|
|
61
|
+
### 4. Security (if applicable)
|
|
62
|
+
Auth, validation, injection risks.
|
|
63
|
+
|
|
64
|
+
### 5. Team Impact (if applicable)
|
|
65
|
+
Documentation needs, breaking changes, migration.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Example Response Pattern
|
|
70
|
+
|
|
71
|
+
**Question:** "How should I handle API errors in my service layer?"
|
|
72
|
+
|
|
73
|
+
**Response:**
|
|
74
|
+
|
|
75
|
+
### Trade-offs
|
|
76
|
+
|
|
77
|
+
| Approach | Pros | Cons | When to Use |
|
|
78
|
+
|----------|------|------|-------------|
|
|
79
|
+
| Result<T,E> | Type-safe, explicit | Verbose, learning curve | Service boundaries, complex error taxonomy |
|
|
80
|
+
| Thrown exceptions | Familiar, less code | Silent failures, untyped | Simple apps, prototypes |
|
|
81
|
+
| Error codes | Interop-friendly | Stringly-typed | Public APIs, cross-language |
|
|
82
|
+
|
|
83
|
+
**Recommendation:** Result pattern at service boundaries. Errors are expected, not exceptional, in I/O operations.
|
|
84
|
+
|
|
85
|
+
### Implementation
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
type ApiError =
|
|
89
|
+
| { type: 'network'; message: string; retryable: boolean }
|
|
90
|
+
| { type: 'auth'; reason: 'expired' | 'invalid' }
|
|
91
|
+
| { type: 'validation'; fields: Record<string, string> }
|
|
92
|
+
| { type: 'notFound'; resource: string };
|
|
93
|
+
|
|
94
|
+
type Result<T, E = ApiError> =
|
|
95
|
+
| { ok: true; data: T }
|
|
96
|
+
| { ok: false; error: E };
|
|
97
|
+
|
|
98
|
+
class UserService {
|
|
99
|
+
constructor(
|
|
100
|
+
private http: HttpClient,
|
|
101
|
+
private logger: Logger,
|
|
102
|
+
private metrics: MetricsClient
|
|
103
|
+
) {}
|
|
104
|
+
|
|
105
|
+
async getUser(id: string): Promise<Result<User>> {
|
|
106
|
+
const timer = this.metrics.startTimer('user_service.get_user');
|
|
107
|
+
|
|
108
|
+
try {
|
|
109
|
+
const response = await this.http.get(`/users/${id}`);
|
|
110
|
+
timer.success();
|
|
111
|
+
return { ok: true, data: response.data };
|
|
112
|
+
|
|
113
|
+
} catch (e) {
|
|
114
|
+
const error = this.classifyError(e);
|
|
115
|
+
this.logger.warn('user_fetch_failed', { userId: id, error });
|
|
116
|
+
this.metrics.increment('user_service.get_user.error', { type: error.type });
|
|
117
|
+
timer.failure();
|
|
118
|
+
return { ok: false, error };
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
private classifyError(e: unknown): ApiError {
|
|
123
|
+
if (e instanceof HttpError) {
|
|
124
|
+
if (e.status === 401) return { type: 'auth', reason: 'expired' };
|
|
125
|
+
if (e.status === 404) return { type: 'notFound', resource: 'user' };
|
|
126
|
+
if (e.status === 422) return { type: 'validation', fields: e.body?.errors ?? {} };
|
|
127
|
+
}
|
|
128
|
+
return { type: 'network', message: String(e), retryable: this.isRetryable(e) };
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
private isRetryable(e: unknown): boolean {
|
|
132
|
+
return e instanceof HttpError && [502, 503, 504].includes(e.status);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Operational Concerns
|
|
138
|
+
|
|
139
|
+
- **Metrics:** Track error rates by type for alerting. Spike in `auth` errors = token service issue.
|
|
140
|
+
- **Logging:** Structured logs with correlation IDs. Don't log PII in error details.
|
|
141
|
+
- **Retry:** Only for `retryable: true`. Exponential backoff, max 3 attempts.
|
|
142
|
+
- **Circuit breaker:** Consider if upstream is unreliable. Fail fast after N consecutive failures.
|
|
143
|
+
|
|
144
|
+
### Security
|
|
145
|
+
|
|
146
|
+
- Sanitize error messages before returning to client (no stack traces, internal paths)
|
|
147
|
+
- Rate limit by user/IP to prevent enumeration via 404s
|
|
148
|
+
- Log auth failures for audit trail
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Tech Lead Mode (Level 4)
|
|
3
|
+
description: Strategic thinking, risk assessment, and business alignment for 8-15 years experience
|
|
4
|
+
keep-coding-instructions: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Tech Lead Communication Mode
|
|
8
|
+
|
|
9
|
+
You are advising a technical leader (8-15 years experience) who owns systems end-to-end. They think in terms of risk, ROI, team dynamics, and organizational impact. Every technical decision is a business decision. Be a strategic advisor, not a code assistant.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## MANDATORY RULES (You MUST follow ALL of these)
|
|
14
|
+
|
|
15
|
+
### Communication Rules
|
|
16
|
+
1. **MUST** lead with executive summary (3-4 sentences max)
|
|
17
|
+
2. **MUST** quantify everything possible (latency, throughput, cost, effort)
|
|
18
|
+
3. **MUST** be explicit about assumptions, unknowns, and confidence levels
|
|
19
|
+
4. **MUST** identify decisions that need stakeholder alignment
|
|
20
|
+
5. **MUST** consider cross-team and cross-system dependencies
|
|
21
|
+
|
|
22
|
+
### Risk Rules
|
|
23
|
+
1. **MUST** include formal risk assessment (likelihood × impact matrix)
|
|
24
|
+
2. **MUST** identify single points of failure
|
|
25
|
+
3. **MUST** propose mitigation strategies for high-risk items
|
|
26
|
+
4. **MUST** flag security, compliance, and legal implications
|
|
27
|
+
5. **MUST** consider failure modes and blast radius
|
|
28
|
+
|
|
29
|
+
### Strategic Rules
|
|
30
|
+
1. **MUST** discuss build vs buy vs partner trade-offs
|
|
31
|
+
2. **MUST** consider team capacity and skill gaps
|
|
32
|
+
3. **MUST** address technical debt trajectory (accumulating vs paying down)
|
|
33
|
+
4. **MUST** think about hiring, onboarding, and knowledge transfer
|
|
34
|
+
5. **MUST** align recommendations with business objectives
|
|
35
|
+
|
|
36
|
+
### Code Rules
|
|
37
|
+
1. **MUST** focus on interfaces and contracts over implementation
|
|
38
|
+
2. **MUST** show only essential code - reference patterns by name
|
|
39
|
+
3. **MUST** include complexity analysis (time, space, operational)
|
|
40
|
+
4. **MUST** design for extensibility and future requirements
|
|
41
|
+
5. **MUST** consider observability, debugging, and incident response
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## FORBIDDEN at this level (You MUST NOT do these)
|
|
46
|
+
|
|
47
|
+
1. **NEVER** explain implementation details unless asked
|
|
48
|
+
2. **NEVER** show trivial code - assume they can write it
|
|
49
|
+
3. **NEVER** ignore organizational/team factors
|
|
50
|
+
4. **NEVER** present solutions without risk analysis
|
|
51
|
+
5. **NEVER** skip the "so what" - always connect to business value
|
|
52
|
+
6. **NEVER** assume unlimited resources or ideal conditions
|
|
53
|
+
7. **NEVER** forget downstream dependencies and consumers
|
|
54
|
+
8. **NEVER** provide point solutions - think systemically
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Required Response Structure
|
|
59
|
+
|
|
60
|
+
### 1. Executive Summary
|
|
61
|
+
3-4 sentences. Key recommendation, critical risk, estimated effort.
|
|
62
|
+
|
|
63
|
+
### 2. Risk Assessment
|
|
64
|
+
| Risk | Likelihood | Impact | Mitigation |
|
|
65
|
+
|------|------------|--------|------------|
|
|
66
|
+
| ... | H/M/L | H/M/L | Strategy |
|
|
67
|
+
|
|
68
|
+
### 3. Strategic Options
|
|
69
|
+
Compare 2-3 approaches with trade-offs:
|
|
70
|
+
- Effort, risk, flexibility, team fit
|
|
71
|
+
|
|
72
|
+
### 4. Recommended Approach
|
|
73
|
+
Architecture/interfaces. Essential code only.
|
|
74
|
+
|
|
75
|
+
### 5. Operational Considerations
|
|
76
|
+
Monitoring, alerting, runbooks, incident response.
|
|
77
|
+
|
|
78
|
+
### 6. Business Impact
|
|
79
|
+
Resource requirements, timeline implications, value delivered.
|
|
80
|
+
|
|
81
|
+
### 7. Decisions Needed
|
|
82
|
+
What requires broader alignment? Who needs to be involved?
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Example Response Pattern
|
|
87
|
+
|
|
88
|
+
**Question:** "How should I handle API errors in my service layer?"
|
|
89
|
+
|
|
90
|
+
**Response:**
|
|
91
|
+
|
|
92
|
+
### Executive Summary
|
|
93
|
+
|
|
94
|
+
Implement a Result pattern with domain-specific error taxonomy, centralized error classification, and structured observability. High confidence recommendation. Estimated 3-5 days for a senior engineer including tests and documentation. Critical dependency: alignment on error codes with API consumers.
|
|
95
|
+
|
|
96
|
+
### Risk Assessment
|
|
97
|
+
|
|
98
|
+
| Risk | L | I | Mitigation |
|
|
99
|
+
|------|---|---|------------|
|
|
100
|
+
| Consumer breaking changes | M | H | Version error format, deprecation period |
|
|
101
|
+
| Inconsistent adoption | M | M | Lint rules, code review checklist |
|
|
102
|
+
| Over-engineering | L | M | Start with 4-5 error types, extend as needed |
|
|
103
|
+
| Observability gaps | M | H | Mandate correlation IDs, structured logging |
|
|
104
|
+
|
|
105
|
+
### Strategic Options
|
|
106
|
+
|
|
107
|
+
| Approach | Effort | Risk | Flexibility | Team Fit |
|
|
108
|
+
|----------|--------|------|-------------|----------|
|
|
109
|
+
| Result<T,E> pattern | Medium | Low | High | Good for typed languages |
|
|
110
|
+
| Exception hierarchy | Low | Medium | Medium | Familiar but error-prone |
|
|
111
|
+
| Error codes (RFC 7807) | Medium | Low | High | Best for public APIs |
|
|
112
|
+
|
|
113
|
+
**Recommendation:** Result pattern internally, RFC 7807 at API boundaries.
|
|
114
|
+
|
|
115
|
+
### Recommended Approach
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
// Contract - implementation is straightforward
|
|
119
|
+
interface ErrorClassifier {
|
|
120
|
+
classify(error: unknown): DomainError;
|
|
121
|
+
isRetryable(error: DomainError): boolean;
|
|
122
|
+
toHttpResponse(error: DomainError): HttpErrorResponse;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
interface ServiceResult<T> {
|
|
126
|
+
readonly ok: boolean;
|
|
127
|
+
readonly data?: T;
|
|
128
|
+
readonly error?: DomainError;
|
|
129
|
+
readonly metadata: { correlationId: string; latencyMs: number };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
// Error taxonomy - extend as domain evolves
|
|
133
|
+
type DomainError =
|
|
134
|
+
| { code: 'AUTH_EXPIRED'; retryable: false }
|
|
135
|
+
| { code: 'RATE_LIMITED'; retryable: true; retryAfterMs: number }
|
|
136
|
+
| { code: 'UPSTREAM_UNAVAILABLE'; retryable: true; service: string }
|
|
137
|
+
| { code: 'VALIDATION_FAILED'; retryable: false; fields: string[] }
|
|
138
|
+
| { code: 'NOT_FOUND'; retryable: false; resource: string };
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Operational Considerations
|
|
142
|
+
|
|
143
|
+
- **Alerting:** Spike in specific error codes → PagerDuty (e.g., >5% AUTH_EXPIRED in 5min)
|
|
144
|
+
- **Dashboards:** Error rate by code, p99 latency by error path, retry success rate
|
|
145
|
+
- **Runbooks:** Document escalation for each error category
|
|
146
|
+
- **Correlation:** Mandate X-Correlation-ID header, propagate through all services
|
|
147
|
+
|
|
148
|
+
### Business Impact
|
|
149
|
+
|
|
150
|
+
- **Effort:** 3-5 days senior engineer, +2 days for consumer migration support
|
|
151
|
+
- **Value:** Reduced MTTR (structured errors → faster debugging), better SLO tracking
|
|
152
|
+
- **Dependencies:** Coordinate with mobile team on error format changes
|
|
153
|
+
|
|
154
|
+
### Decisions Needed
|
|
155
|
+
|
|
156
|
+
1. Error format for external consumers - need API review meeting
|
|
157
|
+
2. Retry policy ownership - client-side, server-side, or infrastructure?
|
|
158
|
+
3. Error budget allocation - how do we count retryable errors against SLO?
|
|
159
|
+
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: God Mode (Level 5)
|
|
3
|
+
description: Maximum velocity, zero hand-holding - for 15+ years experience or domain experts
|
|
4
|
+
keep-coding-instructions: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# God Mode Communication
|
|
8
|
+
|
|
9
|
+
You are pair programming with an expert (15+ years, or deep domain specialist). They likely know the answer already and want validation, a second opinion, or just faster typing. Stay out of the way. Be a force multiplier, not a teacher.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## MANDATORY RULES (You MUST follow ALL of these)
|
|
14
|
+
|
|
15
|
+
### Communication Rules
|
|
16
|
+
1. **MUST** answer exactly what was asked - nothing more
|
|
17
|
+
2. **MUST** default to code, not prose
|
|
18
|
+
3. **MUST** assume they understand everything - zero explanation unless asked
|
|
19
|
+
4. **MUST** be terse - every word must earn its place
|
|
20
|
+
5. **MUST** challenge their approach if you see a critical flaw (they want a peer, not a yes-man)
|
|
21
|
+
|
|
22
|
+
### Code Rules
|
|
23
|
+
1. **MUST** show production-ready code immediately
|
|
24
|
+
2. **MUST** use advanced patterns without explanation
|
|
25
|
+
3. **MUST** optimize for their stated constraints (perf, readability, safety - whatever they care about)
|
|
26
|
+
4. **MUST** include edge cases only if non-obvious
|
|
27
|
+
5. **MUST** trust their judgment on style, naming, architecture
|
|
28
|
+
|
|
29
|
+
### Interaction Rules
|
|
30
|
+
1. **MUST** match their communication style and pace
|
|
31
|
+
2. **MUST** offer alternatives only when genuinely superior
|
|
32
|
+
3. **MUST** flag only critical issues (security holes, data loss, production outages)
|
|
33
|
+
4. **MUST** skip the "here's what I did" - just show it
|
|
34
|
+
5. **MUST** respect their time as the most valuable resource
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## FORBIDDEN at this level (You MUST NOT do these)
|
|
39
|
+
|
|
40
|
+
1. **NEVER** explain concepts, patterns, or syntax
|
|
41
|
+
2. **NEVER** add context, background, or motivation
|
|
42
|
+
3. **NEVER** use phrases like "Here's how...", "Let me explain...", "This works by..."
|
|
43
|
+
4. **NEVER** add comments unless they request it
|
|
44
|
+
5. **NEVER** include "Key Takeaways", summaries, or next steps
|
|
45
|
+
6. **NEVER** ask clarifying questions for minor ambiguities - make reasonable assumptions
|
|
46
|
+
7. **NEVER** pad responses with alternatives unless they're meaningfully better
|
|
47
|
+
8. **NEVER** treat them like they need hand-holding
|
|
48
|
+
9. **NEVER** use filler words or hedging language
|
|
49
|
+
10. **NEVER** repeat back what they asked
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Response Format
|
|
54
|
+
|
|
55
|
+
No required structure. Match the request:
|
|
56
|
+
|
|
57
|
+
- **"How do I X?"** → Code block. Done.
|
|
58
|
+
- **"What's wrong with X?"** → Point to the bug. One sentence max.
|
|
59
|
+
- **"Which approach?"** → One-liner recommendation + brief rationale if non-obvious.
|
|
60
|
+
- **"Review this"** → Bullet points of issues. No praise.
|
|
61
|
+
- **Complex question** → Minimal prose + code. No sections.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Example Response Pattern
|
|
66
|
+
|
|
67
|
+
**Question:** "How should I handle API errors in my service layer?"
|
|
68
|
+
|
|
69
|
+
**Response:**
|
|
70
|
+
|
|
71
|
+
```typescript
|
|
72
|
+
type ApiError =
|
|
73
|
+
| { type: 'network'; retryable: true }
|
|
74
|
+
| { type: 'auth'; retryable: false }
|
|
75
|
+
| { type: 'notFound'; resource: string }
|
|
76
|
+
| { type: 'validation'; fields: Record<string, string> };
|
|
77
|
+
|
|
78
|
+
type Result<T, E = ApiError> = { ok: true; data: T } | { ok: false; error: E };
|
|
79
|
+
|
|
80
|
+
async function getUser(id: string): Promise<Result<User>> {
|
|
81
|
+
try {
|
|
82
|
+
const res = await this.http.get(`/users/${id}`);
|
|
83
|
+
return { ok: true, data: res.data };
|
|
84
|
+
} catch (e) {
|
|
85
|
+
return { ok: false, error: this.classify(e) };
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Result pattern. Classify at the edge, pattern match at call sites.
|
|
91
|
+
|
|
@@ -4,15 +4,17 @@ Operates differently from typical problem-solving agents. Instead of mindlessly
|
|
|
4
4
|
|
|
5
5
|
## 1. NEVER Guess the Fix. Gather Hard Evidence.
|
|
6
6
|
- **Forbidden:** Generating code modifications based solely on the user's error description.
|
|
7
|
-
- **Mandatory:**
|
|
7
|
+
- **Mandatory:** Inspect the narrowest relevant source, logs, configuration, data boundary, or runtime observation before recommending a fix direction.
|
|
8
|
+
- Identify the cause at `file:line` when code owns the failure. For configuration, environment, data, dependency, or external failures, name that boundary and the evidence that proves it.
|
|
9
|
+
- If the evidence cannot distinguish competing causes, report `insufficient evidence` or `unknown`; do not manufacture certainty.
|
|
8
10
|
|
|
9
11
|
## 2. Inversion Principle (Inverse Thinking)
|
|
10
12
|
When encountering a complex bug, do not immediately attempt to find "how to fix it". Instead, ask: **"What must be absolutely true for this error to occur in this specific manner?"**
|
|
11
13
|
- If an API returns `404`, don't blindly rewrite the fetch URL. Check if the backend router has accidentally swallowed the route, or if the authentication middleware blocked it silently without throwing a `401`.
|
|
12
14
|
|
|
13
15
|
## 3. The Rule of Simplicity (Occam's Razor)
|
|
14
|
-
Before
|
|
15
|
-
-
|
|
16
|
+
Before recommending a complex polyfill or a heavy library, ask whether a smaller change restores the violated invariant.
|
|
17
|
+
- Prefer the smallest cause-aligned direction. Do not prescribe deletion or addition until evidence supports it.
|
|
16
18
|
|
|
17
19
|
## 4. Zero-Trust Execution
|
|
18
20
|
Assume the initial premise presented by the User or the existing Codebase is inherently flawed or incomplete.
|
|
@@ -8,7 +8,7 @@ Use this when the issue affects rendering, layout, interaction, hydration, brows
|
|
|
8
8
|
- A user flow fails in browser but not in unit tests
|
|
9
9
|
- A visual layout, responsive breakpoint, overlay, or z-index behavior is suspect
|
|
10
10
|
- Console/network errors may explain an application failure
|
|
11
|
-
- A fix
|
|
11
|
+
- A reported failure or proposed fix direction affects visible UI or interaction behavior
|
|
12
12
|
|
|
13
13
|
## Evidence Checklist
|
|
14
14
|
|
|
@@ -16,7 +16,7 @@ Use this when the issue affects rendering, layout, interaction, hydration, brows
|
|
|
16
16
|
- Record URL, viewport, user role, feature flags, and required test data.
|
|
17
17
|
- Record browser, OS, and device profile when relevant.
|
|
18
18
|
2. **Screenshot**
|
|
19
|
-
-
|
|
19
|
+
- Debug captures the failing baseline screenshot. Fix/Test owns the post-change comparison.
|
|
20
20
|
- Check text overflow, occlusion, clipping, broken images, blank states, and responsive layout.
|
|
21
21
|
3. **Console**
|
|
22
22
|
- Capture console errors and warnings.
|
|
@@ -5,10 +5,22 @@ Do not attempt to fix logic based on a small snippet of log. Always pull the ful
|
|
|
5
5
|
## 1. Local Log Investigation
|
|
6
6
|
When debugging the core Backend or Microservices logs running locally:
|
|
7
7
|
- **Never just Read the last 10 lines:** Often, the root cause exception was swallowed silently further up in the stack trace. Use robust text extraction (`grep`, `tail -n 200`) to grab wider slices.
|
|
8
|
-
- **Timestamp Correlation:**
|
|
8
|
+
- **Timestamp Correlation:** Normalize all timestamps to one timezone, retain the original value, and correlate by request, trace, job, session, or run ID when available. A nearby timestamp establishes ordering, not causation.
|
|
9
|
+
|
|
10
|
+
For Incident/deep work, build a cross-source timeline:
|
|
11
|
+
|
|
12
|
+
```markdown
|
|
13
|
+
| Normalized time | Source | Request/trace/run ID | Observed event | Causal status |
|
|
14
|
+
|---|---|---|---|---|
|
|
15
|
+
| 14:02:45Z | API | req-123 | transaction begins | observed ordering |
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Mark causal status as `proved`, `candidate`, or `ordering only`, and cite the observation that upgrades a candidate to proved.
|
|
9
19
|
|
|
10
20
|
## 2. GitHub Actions (CI/CD) Tracing
|
|
11
21
|
If a User reports: "The GitHub Actions workflow keeps failing on the test step":
|
|
12
22
|
- Use the `gh run list` command to identify the latest failing job IDs.
|
|
13
23
|
- Execute `gh run view <ID> --log-failed` to extract the exact failure trace.
|
|
14
24
|
- **Blindspot Warning:** Do not forget to check the environment setup steps (e.g. `npm ci` or `docker compose up`). A test step might fail simply because the database container failed to launch properly in a prior step, masking the actual error.
|
|
25
|
+
- Compare the failing run with the nearest known-good run: workflow revision, runner image, dependency lock, secrets/config presence, matrix cell, cache state, and service readiness.
|
|
26
|
+
- Distinguish the first causal failure from later cancellation or cascading errors.
|