From 3a559a58f6e9c56428409bf5fefc5d15cb52472a Mon Sep 17 00:00:00 2001 From: asepharyana Date: Sat, 25 Jul 2026 12:05:00 +0700 Subject: [PATCH] feat(hub-guide): add 'ask when ambiguous' principle across skills - Add principle #25 to engineering-principles: 'Ask When Ambiguous' - Add 'Ask When Ambiguous' section to design-patterns and clean-architecture - Update detect-project.sh hook to reinforce ask-don't-assume behavior --- hooks/scripts/detect-project.sh | 1 + skills/clean-architecture/SKILL.md | 7 +++++++ skills/design-patterns/SKILL.md | 7 +++++++ skills/engineering-principles/SKILL.md | 12 ++++++++++++ 4 files changed, 27 insertions(+) diff --git a/hooks/scripts/detect-project.sh b/hooks/scripts/detect-project.sh index 2f3f53d..73232ce 100755 --- a/hooks/scripts/detect-project.sh +++ b/hooks/scripts/detect-project.sh @@ -73,3 +73,4 @@ if [ -n "$SKILLS" ]; then echo "📐 [hub-guide] project-specific: ${SKILLS}" fi echo "📐 [hub-guide] Apply these best-practice rules throughout this session." +echo "📐 [hub-guide] When in doubt about intent or approach — ask instead of assuming." diff --git a/skills/clean-architecture/SKILL.md b/skills/clean-architecture/SKILL.md index b665205..e723717 100644 --- a/skills/clean-architecture/SKILL.md +++ b/skills/clean-architecture/SKILL.md @@ -85,6 +85,13 @@ When the task calls for it, load: - **[references/solid.md](references/solid.md)** — Full SOLID treatment (SRP, OCP, LSP, ISP, DIP). Component principles (REP, CCP, CRP, ADP, SDP, SAP). Examples for each principle, historical evolution, and practical tests for violations. +## Ask When Ambiguous + +When the module boundary is unclear, ask rather than guessing: +- "Should this live in domain or application layer? Is it a pure business rule or an orchestration concern?" +- "Is this a port (interface declared by application) or an adapter (implementation in infrastructure)?" +- If you're not sure which layer a piece of logic belongs to, flag it with a brief question. A wrong boundary assumption is expensive to refactor later. + ## Anti-patterns - ❌ Business logic in route handlers or controllers diff --git a/skills/design-patterns/SKILL.md b/skills/design-patterns/SKILL.md index e0c94aa..aa2d1e0 100644 --- a/skills/design-patterns/SKILL.md +++ b/skills/design-patterns/SKILL.md @@ -81,6 +81,13 @@ When the task calls for it, load: - **[references/catalog.md](references/catalog.md)** — Full GoF pattern catalog with code examples, real-world usage, modern alternatives, and "when to NOT use" guidance for each pattern. +## Ask When Ambiguous + +When multiple patterns could apply, present a brief comparison and ask which direction fits: +- "This could use Strategy (if algorithms vary) or polymorphism on a factory (if types vary). Which axis of change do you expect to grow?" +- If you're unsure what pattern fits, say so. Don't force a pattern where a simple function suffices. +- If the problem is too vague to pattern-match, ask clarifying questions first. A pattern chosen on partial input is technical debt. + ## Anti-patterns - ❌ **Pattern for pattern's sake** — a simple function is better than a Strategy class with one implementation diff --git a/skills/engineering-principles/SKILL.md b/skills/engineering-principles/SKILL.md index 09b9b5d..59360d6 100644 --- a/skills/engineering-principles/SKILL.md +++ b/skills/engineering-principles/SKILL.md @@ -199,3 +199,15 @@ One commit = one logical change. Not a mix of refactor + feature + bug fix in on - A clean diff means a fast review and a readable history. - If your commit message needs "and," your commit is too large. - `git add -p` is your friend. Stage related changes together, unrelated changes separately. + +## 25. Ask When Ambiguous — Never Assume + +When requirements are unclear, the user's intent is uncertain, or there are multiple valid approaches, **ask** instead of guessing. Assumptions create waste: wrong implementation, rework, and frustration. + +- **Ambiguous request?** Ask 1-2 focused clarifying questions before writing code. Don't silently pick one interpretation. +- **Multiple valid approaches?** Briefly compare trade-offs and ask which one fits. Don't default to your favorite. +- **Missing context?** Ask for it. Don't infer from partial input. +- **One clarifying question is better than five.** Ask the minimum to unblock. +- **If you must assume, state your assumption explicitly** — "Assuming this is a server component since you mentioned API routes. Say so if you need it to be a client component." + +The goal: write code once, correctly, based on what the user actually wants — not what you guessed they wanted.