devstack 0.1.0

package/vendor/skills/skills/no-workarounds/SKILL.md

@@ -0,0 +1,447 @@
+---
+name: no-workarounds
+description: Enforce root-cause fixes over workarounds, hacks, and symptom patches in all software engineering tasks. Use when debugging issues, fixing bugs, resolving test failures, planning solutions, making architectural decisions, or reviewing code changes. Activates gate functions that detect and reject common workaround patterns such as type assertions, lint suppressions, error swallowing, timing hacks, and monkey patches. Don't use for trivial formatting changes or documentation-only edits.
+---
+
+# No Workarounds
+
+## The Fundamental Law
+
+```
+A WORKAROUND IS A LIE TOLD TO THE COMPILER.
+It makes the symptom disappear while the disease spreads.
+```
+
+A workaround is any change that makes a problem stop manifesting without addressing why the problem exists. Workarounds are not fixes. They are deferred failures with compound interest.
+
+**Philosophical foundation:** Read `references/philosophical-foundations.md` for the engineering principles behind this skill, drawn from Toyota's Jidoka, Fowler's Technical Debt Quadrant, Torvalds' "good taste," and the Broken Windows Theory.
+
+## When to Use
+
+Activate this skill for ANY of:
+
+- Debugging bugs or test failures
+- Fixing errors or unexpected behavior
+- Planning implementation approaches
+- Reviewing code changes (own or others')
+- Resolving build, lint, or typecheck failures
+- Making architectural decisions
+- Addressing performance problems
+- Responding to code review feedback
+
+**Activate ESPECIALLY when:**
+
+- Under time pressure (urgency creates workaround temptation)
+- A "quick fix" seems obvious (obvious fixes are often symptom patches)
+- Fixing someone else's code (unfamiliarity breeds workarounds)
+- A test is flaky or failing intermittently (timing workarounds are the worst kind)
+
+## The Workaround Detection Gate
+
+```
+BEFORE writing or proposing ANY fix:
+
+1. STATE the problem clearly
+2. ASK: "Why does this problem exist?" (not "How do I make it stop?")
+3. TRACE to root cause (use systematic-debugging skill)
+4. ASK: "Does my proposed fix address the ROOT CAUSE?"
+5. ASK: "Would this fix be necessary if the code were correct?"
+6. ASK: "Am I silencing a signal or fixing a source?"
+
+IF any answer reveals symptom-patching:
+  STOP — Redesign the fix to address root cause
+
+IF root cause is in external code or truly unfixable:
+  Document why, add defensive validation, and mark with WORKAROUND comment
+  (See "The Escape Valve" section below)
+```
+
+## The Seven Categories of Workarounds
+
+### Category 1: Type System Evasion
+
+**The signal being silenced:** The type system is telling the code is wrong.
+
+```typescript
+// WORKAROUND: Lying to the compiler
+const value = response.data as UserProfile;
+const config = {} as AppConfig;
+function process(input: any) { ... }
+
+// PROPER FIX: Make types truthful
+const value: UserProfile | undefined = response.data;
+if (!value) throw new Error("Missing user profile");
+
+const config: AppConfig = { theme: "light", locale: "en" };
+
+function process(input: UserProfile) { ... }
+```
+
+**Gate function:**
+
+```
+BEFORE using `as`, `any`, `unknown` cast, or `!` (non-null assertion):
+  Ask: "Why doesn't the type match?"
+
+  IF the data shape is genuinely unknown:
+    Use runtime validation (Schema, Zod, or type guards)
+  IF the type is wrong:
+    Fix the type definition
+  IF the API returns unexpected shape:
+    Fix the API contract or add a validation layer
+  NEVER use type assertions to bypass compiler errors
+```
+
+### Category 2: Lint and Warning Suppression
+
+**The signal being silenced:** Static analysis found a real problem.
+
+```typescript
+// WORKAROUND: Shooting the messenger
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const result = fetchData();
+
+// @ts-ignore
+someFunction(wrongArgs);
+
+// @ts-expect-error - TODO fix later
+brokenCall();
+
+// PROPER FIX: Fix what the linter found
+fetchData(); // Remove unused binding
+
+someFunction(correctArgs); // Fix the arguments
+```
+
+**Gate function:**
+
+```
+BEFORE adding eslint-disable, @ts-ignore, @ts-expect-error, or any suppression:
+  Ask: "What rule is being violated and WHY?"
+
+  IF the code genuinely violates the rule:
+    Fix the code, not the linter
+  IF the rule is wrong for this codebase:
+    Disable the rule in config (globally), not inline
+  IF it's a third-party type issue:
+    File an issue, add a minimal typed wrapper
+  NEVER suppress a warning without understanding it
+```
+
+### Category 3: Error Swallowing
+
+**The signal being silenced:** Something failed and the code pretends it didn't.
+
+```typescript
+// WORKAROUND: Pretending errors don't exist
+try {
+  await saveData(payload);
+} catch {
+  // silently ignore
+}
+
+try {
+  result = JSON.parse(input);
+} catch {
+  result = {}; // default to empty - hides corrupt data
+}
+
+// PROPER FIX: Handle errors meaningfully
+try {
+  await saveData(payload);
+} catch (error) {
+  logger.error("Failed to save data", { error, payload });
+  throw new SaveError("Data save failed", { cause: error });
+}
+
+const parsed = Schema.decodeUnknownSync(PayloadSchema)(input);
+// Throws descriptive error if input is invalid
+```
+
+**Gate function:**
+
+```
+BEFORE writing a catch block:
+  Ask: "What specific errors can occur here?"
+  Ask: "What should happen when each error occurs?"
+
+  IF the answer is "ignore it":
+    STOP — Ignoring errors hides bugs
+  IF the answer is "log it":
+    Log AND propagate or handle meaningfully
+  IF the answer is "use a default":
+    Ensure the default is SAFE and the failure is LOGGED
+  NEVER write an empty catch block
+  NEVER catch Exception/Error broadly without re-throwing specific types
+```
+
+### Category 4: Timing and Lifecycle Hacks
+
+**The signal being silenced:** Code runs in the wrong order or at the wrong time.
+
+```typescript
+// WORKAROUND: Racing against the clock
+setTimeout(() => {
+  element.focus();
+}, 100);
+
+await new Promise(resolve => setTimeout(resolve, 500));
+// "wait for state to settle"
+
+await retry(() => checkCondition(), { times: 10, delay: 200 });
+// retry loop hiding a race condition
+
+// PROPER FIX: Fix the lifecycle
+// Use framework-native lifecycle hooks
+useEffect(() => {
+  if (ref.current) ref.current.focus();
+}, [isVisible]);
+
+// Use proper event-driven coordination
+await waitForEvent(emitter, "ready");
+
+// Use condition-based polling (not blind retries)
+await waitUntil(() => service.isReady(), {
+  timeout: 5000,
+  message: "Service failed to become ready",
+});
+```
+
+**Gate function:**
+
+```
+BEFORE adding setTimeout, delay, sleep, or retry loops:
+  Ask: "WHY is the timing wrong?"
+  Ask: "What event signals that the system is ready?"
+
+  IF there's an event or callback available:
+    Use it instead of arbitrary delays
+  IF the ordering is wrong:
+    Fix the initialization order
+  IF it's a test timing issue:
+    Use condition-based waiting, never arbitrary sleeps
+  NEVER use setTimeout(fn, 0) to "fix" rendering issues
+  NEVER use arbitrary delays to "wait for things to settle"
+```
+
+### Category 5: Monkey Patching and Runtime Mutation
+
+**The signal being silenced:** The API doesn't do what the code needs.
+
+```typescript
+// WORKAROUND: Mutating things you don't own
+Array.prototype.customMethod = function () { ... };
+Object.defineProperty(window, "fetch", { value: customFetch });
+library.internals._privateMethod = replacement;
+
+// PROPER FIX: Composition over mutation
+function customOperation<T>(arr: T[]): T[] { ... }
+const wrappedFetch = createFetchWrapper(window.fetch);
+const adapter = new LibraryAdapter(library);
+```
+
+**Gate function:**
+
+```
+BEFORE modifying prototypes, globals, or third-party internals:
+  Ask: "Does the library provide an extension point?"
+
+  IF yes: Use the official extension mechanism
+  IF no: Wrap with composition/adapter pattern
+  IF the library is broken: File issue, fork, or find alternative
+  NEVER modify objects the code doesn't own
+```
+
+### Category 6: Defensive Duplication
+
+**The signal being silenced:** The data is unreliable at its source.
+
+```typescript
+// WORKAROUND: Checking everywhere because source is broken
+function renderUser(user: User) {
+  const name = user?.name ?? user?.displayName ?? "Unknown";
+  const email = user?.email ?? user?.contacts?.email ?? "";
+  const id = user?.id ?? user?.userId ?? user?._id ?? "";
+  // ... 20 more optional chains
+}
+
+// PROPER FIX: Validate once at the boundary
+const user = Schema.decodeUnknownSync(UserSchema)(rawData);
+// user is now guaranteed to have correct shape
+
+function renderUser(user: User) {
+  // No defensive checks needed — schema validated at entry
+  return `${user.name} (${user.email})`;
+}
+```
+
+**Gate function:**
+
+```
+BEFORE adding optional chaining (?.) or nullish coalescing (??) deeply:
+  Ask: "Why might this value be missing?"
+  Ask: "Where does this data enter the system?"
+
+  IF data is unvalidated at entry:
+    Add validation at the boundary, remove defensive checks downstream
+  IF the type allows undefined but shouldn't:
+    Fix the type to be non-optional
+  IF it's truly optional:
+    Handle the None/undefined case explicitly at the nearest decision point
+  NEVER scatter optional chains as a substitute for proper validation
+```
+
+### Category 7: Copy-Paste Adaptation
+
+**The signal being silenced:** The abstraction doesn't fit but the developer forces it.
+
+```typescript
+// WORKAROUND: Copy and "adapt" (badly)
+// Copied from UserService and changed 3 lines
+function createProject(data: ProjectData) {
+  // 200 lines, 95% identical to createUser
+  // but with subtle bugs from incomplete adaptation
+}
+
+// PROPER FIX: Extract shared pattern or write fresh
+// Option A: Extract the common pattern
+function createEntity<T>(schema: Schema<T>, repo: Repository<T>) {
+  return (data: T) => pipe(Schema.decode(schema)(data), Effect.flatMap(repo.insert));
+}
+
+// Option B: Write purpose-built code
+function createProject(data: ProjectData) {
+  // Clean, focused implementation for projects
+}
+```
+
+**Gate function:**
+
+```
+BEFORE copying code and modifying it:
+  Ask: "Am I copying because the pattern is the same or because I'm lazy?"
+
+  IF the pattern is genuinely the same:
+    Extract a shared abstraction first, then use it
+  IF the pattern is similar but different:
+    Write purpose-built code — similar-looking code with different intent
+    should NOT be forced into the same abstraction
+  NEVER copy-paste more than 5 lines without questioning why
+```
+
+## The Compound Cost Formula
+
+```
+Cost of workaround = immediate_time_saved
+                   + (confusion_cost × number_of_developers)
+                   + (debugging_time × number_of_incidents)
+                   + (copy_spread × number_of_imitators)
+                   + (technical_debt_interest × months_until_fix)
+```
+
+A workaround that saves 30 minutes today costs 30 hours when copied to 5 places, debugged 3 times, and confused 4 developers over 6 months.
+
+## Red Flags — STOP and Rethink
+
+Catch these thought patterns and STOP:
+
+| Thought                                     | What It Means                      |
+| ------------------------------------------- | ---------------------------------- |
+| "Just add `as any` to make it compile"      | Type system evasion (Category 1)   |
+| "Disable the lint rule for this line"       | Warning suppression (Category 2)   |
+| "Wrap it in try-catch and ignore the error" | Error swallowing (Category 3)      |
+| "Add a setTimeout to fix the timing"        | Lifecycle hack (Category 4)        |
+| "Override the prototype/global"             | Monkey patching (Category 5)       |
+| "Add `?.` everywhere just to be safe"       | Defensive duplication (Category 6) |
+| "Copy this code and change a few things"    | Copy-paste adaptation (Category 7) |
+| "It works, don't touch it"                  | Fear masking a fragile workaround  |
+| "We'll fix it properly later"               | Later never comes                  |
+| "It's just temporary"                       | Nothing is more permanent          |
+
+## The Escape Valve
+
+Not every problem can be fixed at root cause. When a workaround is genuinely unavoidable:
+
+```
+REQUIRED conditions (ALL must be true):
+  1. Root cause is in external code the team does not control
+  2. The proper fix requires upstream changes with uncertain timeline
+  3. The business impact of NOT shipping exceeds the technical debt cost
+  4. The workaround is ISOLATED (does not leak into other code)
+
+IF all conditions are met:
+  1. Mark with explicit comment: // WORKAROUND: [reason] — see [issue-link]
+  2. File a tracking issue for removal
+  3. Add a test that verifies the workaround behavior
+  4. Add a test that will FAIL when the upstream fix lands (canary test)
+  5. Set a review date (max 90 days)
+
+IF any condition is NOT met:
+  Fix the root cause. No exceptions.
+```
+
+## Quick Reference Decision Tree
+
+```
+Problem detected
+  │
+  ├─ "I know a quick fix" ──→ STOP. Why does the problem exist?
+  │                              │
+  │                              ├─ Root cause identified ──→ Fix root cause
+  │                              │
+  │                              └─ Root cause unclear ──→ Investigate more
+  │                                                         (systematic-debugging)
+  │
+  ├─ "The compiler/linter is wrong" ──→ It's almost never wrong.
+  │                                       │
+  │                                       ├─ Code is wrong ──→ Fix the code
+  │                                       │
+  │                                       └─ Rule is wrong ──→ Change rule in config
+  │                                                             (not inline suppress)
+  │
+  ├─ "The test is flaky" ──→ Flaky = race condition or shared state
+  │                            │
+  │                            ├─ Race condition ──→ Fix ordering/synchronization
+  │                            │
+  │                            └─ Shared state ──→ Isolate test state
+  │
+  └─ "It works but I don't know why" ──→ STOP. Understand before shipping.
+                                           Not understanding = guaranteed future bug.
+```
+
+## Common Rationalizations
+
+| Excuse                                  | Reality                                                             |
+| --------------------------------------- | ------------------------------------------------------------------- |
+| "It's just a small workaround"          | Small workarounds become big patterns when copied                   |
+| "We don't have time for the proper fix" | Workarounds cost MORE time in debugging and maintenance             |
+| "The type system is too strict"         | The type system found a real bug — listen to it                     |
+| "Nobody will copy this"                 | Every workaround in a codebase gets copied within 3 months          |
+| "It's behind a feature flag"            | Feature flags don't expire — the workaround becomes permanent       |
+| "The test passes"                       | A passing test with a workaround tests the workaround, not the code |
+| "I'll create a tech debt ticket"        | 93% of tech debt tickets are never resolved                         |
+| "The external library forces this"      | Use The Escape Valve process above, with all 5 requirements         |
+
+## Integration with Other Skills
+
+This skill works alongside:
+
+- **systematic-debugging** — Provides the root cause investigation methodology
+- **test-anti-patterns** — Prevents workarounds in test code specifically
+- **verification-before-completion** — Ensures the real fix is verified, not the workaround
+- **receiving-code-review** — Evaluates whether review suggestions introduce workarounds
+
+## The Bottom Line
+
+```
+Every workaround is a bet that nobody will ever need to understand this code again.
+That bet always loses.
+
+Fix the disease, not the symptom.
+Fix the source, not the signal.
+Fix the code, not the compiler message.
+```
+
+**For the detailed catalog of 30+ specific workaround patterns with before/after code:** Read `references/workaround-catalog.md`.
+
+**For the philosophical and engineering foundations:** Read `references/philosophical-foundations.md`.

package/vendor/skills/skills/no-workarounds/references/philosophical-foundations.md

@@ -0,0 +1,111 @@
+# Philosophical Foundations
+
+The "no workarounds" principle is not new. It is the convergence of decades of engineering wisdom from manufacturing, software craftsmanship, and systems thinking. These are the intellectual roots.
+
+## 1. Toyota's Jidoka — "Stop and Fix"
+
+**Origin:** Sakichi Toyoda invented a loom that automatically stopped when a thread broke, preventing defective fabric from being produced. Taiichi Ohno, architect of the Toyota Production System, generalized this into the Jidoka principle.
+
+**The principle:** When a defect is detected, STOP the line immediately. Do not pass the defect downstream. Fix the root cause before resuming production.
+
+**Ohno's quote:** "No problem discovered when stopping the line should wait longer than tomorrow morning to be fixed."
+
+**Why it matters for software:** Jeffrey Liker and David Meier identified that "the decision to stop and fix problems as they occur rather than pushing them down the line to be resolved later" is a large part of the difference between Toyota's effectiveness and other companies who tried to adopt lean manufacturing.
+
+**The anti-pattern:** GM's Fremont plant never stopped the assembly line, no matter what. Quality problems were pushed downstream, creating massive rework costs. Toyota stops immediately, and after a few months of ramp-up, their lines run far more reliably.
+
+**Software translation:** A workaround is pushing a defect down the line. It "works" in the moment but creates downstream rework, debugging sessions, and compound failures. Stopping to fix the root cause feels slower but produces vastly better outcomes.
+
+## 2. The Broken Windows Theory
+
+**Origin:** James Q. Wilson and George L. Kelling (1982) observed that a single broken window in a building, left unrepaired, signals that nobody cares — leading to more broken windows, then vandalism, then serious crime.
+
+**Application to software:** Andrew Hunt and Dave Thomas popularized this in "The Pragmatic Programmer" (1999):
+
+> "Don't live with broken windows. Fix each one as soon as it is discovered. If there is insufficient time to fix it properly, then board it up."
+
+**The principle:** One workaround in a codebase signals that workarounds are acceptable. The next developer sees it and thinks "this is how things are done here." Within months, workarounds spread through the codebase like decay.
+
+**Why it matters:** A single `// @ts-ignore` or `as any` in a codebase gives implicit permission for every developer to add their own. The cost is not the individual workaround — it's the culture of workarounds it creates.
+
+## 3. Martin Fowler's Technical Debt Quadrant
+
+**Origin:** Martin Fowler extended Ward Cunningham's debt metaphor into a 2x2 matrix:
+
+|                 | **Reckless**                    | **Prudent**                                   |
+| --------------- | ------------------------------- | --------------------------------------------- |
+| **Deliberate**  | "We don't have time for design" | "We must ship now and deal with consequences" |
+| **Inadvertent** | "What's layering?"              | "Now we know how we should have done it"      |
+
+**The key insight:** Most workarounds are **Reckless-Deliberate** — the team knows it's wrong but does it anyway to save time. This is the most expensive quadrant because it creates a mess, not a strategic debt.
+
+**Uncle Bob's distinction:** Robert C. Martin argued that "a mess is not a technical debt." A mess is sloppy code written without discipline. Technical debt is a conscious, strategic decision with a plan to repay. Calling a mess "technical debt" is an excuse for poor craftsmanship.
+
+**Workarounds are messes, not debts.** They have no repayment plan, no tracking, and no expiration date.
+
+## 4. Linus Torvalds' "Good Taste"
+
+**Origin:** In his 2016 TED Talk, Torvalds illustrated "good taste" with a linked list example. The "bad taste" approach uses a special case (`if` statement) to handle removing the first element. The "good taste" approach uses an indirect pointer, eliminating the special case entirely.
+
+**The principle:** Good taste means writing code that handles edge cases naturally through better design, rather than patching around them with conditional checks.
+
+**Applied to workarounds:** A workaround is always a special case — an `if`, a `try-catch`, a type assertion — bolted onto code that doesn't naturally handle the situation. The proper fix redesigns so the edge case doesn't exist.
+
+## 5. Kent Beck's "Make It Work, Make It Right, Make It Fast"
+
+**Origin:** Attributed to Kent Beck (with roots in Unix philosophy from Butler Lampson, 1983):
+
+1. **Make it work** — Handle one common case
+2. **Make it right** — Handle all cases, refactor
+3. **Make it fast** — Optimize performance
+
+**The critical distinction:** "Make it work" does NOT mean "make it work with workarounds." It means make the core logic correct for the common case. "Make it right" means fix all edge cases and clean up design. Workarounds skip step 2 entirely — they stay at "make it work" forever.
+
+**Beck's TDD formulation:** "Write a test, make it run, make it right." Making it run allows temporary violations of good design. Making it right means refactoring immediately — not in a future sprint, not in a tech debt ticket, NOW.
+
+## 6. Google's Code Health Principles
+
+**Origin:** Google's internal "Code Health" teams publish tips for maintaining codebase quality. Key principles:
+
+- **"Too complex" means "can't be understood quickly by code readers"** — Workarounds add complexity that readers must decode.
+- **Over-engineering is a form of complexity** — But so is under-engineering (workarounds instead of proper abstractions).
+- **Code review exists to improve code health over time** — Not to rubber-stamp workarounds.
+- **YAGNI applies to workarounds too** — If the workaround is "temporary," is it needed at all?
+
+**Google's zero-warnings approach:** Warnings are treated as errors. The build fails on any warning. This eliminates the culture of "it's just a warning."
+
+## 7. The Software Craftsmanship Movement
+
+**Origin:** Sandro Mancuso's "The Software Craftsman" (2014) and the Software Craftsmanship Manifesto:
+
+> "Not only working software, but also well-crafted software."
+> "Not only responding to change, but also steadily adding value."
+
+**The principle:** A craftsperson takes pride in their work. They don't ship work they're not proud of. They don't leave messes for others to clean up.
+
+**Applied to workarounds:** Every workaround is a failure of craftsmanship. It says "I don't care enough about this code to fix it properly." The craftsman's response to time pressure is not "ship the workaround" — it's "negotiate scope, but never negotiate quality."
+
+## 8. The Compounding Effect
+
+All seven principles share a common observation: **problems caught early cost orders of magnitude less to fix than problems caught late.**
+
+| When Caught                    | Relative Cost |
+| ------------------------------ | ------------- |
+| During coding (root cause fix) | 1x            |
+| During code review             | 3x            |
+| During testing                 | 10x           |
+| In staging/QA                  | 30x           |
+| In production                  | 100x          |
+| After users are affected       | 1000x         |
+
+A workaround defers the cost from 1x (fixing now) to 100x+ (fixing in production after the workaround fails in an unexpected way). The "time saved" by a workaround is borrowed at predatory interest rates.
+
+## Summary
+
+These principles converge on one truth:
+
+**The fastest way to build software is to build it correctly.**
+
+Not perfectly. Not over-engineered. But correctly — with honest types, meaningful error handling, proper lifecycle management, and code that says what it means.
+
+Every workaround is a lie that compounds over time. The no-workarounds principle is simply the practice of telling the truth in code.