Skills › gstack › gstack › dx.ts

dx.ts

97 lines · scripts/resolvers/dx.ts at 3f79d81

Open on GitHub

1/**

2 * DX Framework resolver

3 *

4 * Shared principles, characteristics, cognitive patterns, and scoring rubric

5 * for /plan-devex-review and /devex-review. Compact (~150 lines).

6 *

7 * Hall of Fame examples are NOT included here. They live in

8 * plan-devex-review/dx-hall-of-fame.md and are loaded on-demand per pass

9 * to avoid prompt bloat.

10 */

11import type { TemplateContext } from './types';

12import { DX_ERROR_COMPACT, DX_ERROR_ITEMS } from '../../lib/dx-error-contract';

14export function generateDxFramework(ctx: TemplateContext): string {

15 const hallOfFamePath = `${ctx.paths.skillRoot}/plan-devex-review/dx-hall-of-fame.md`;

17 return `## DX First Principles

19These are the laws. Every recommendation traces back to one of these.

211. **Zero friction at T0.** First five minutes decide everything. One click to start. Hello world without reading docs. No credit card. No demo call.

222. **Incremental steps.** Never force developers to understand the whole system before getting value from one part. Gentle ramp, not cliff.

233. **Learn by doing.** Playgrounds, sandboxes, copy-paste code that works in context. Reference docs are necessary but never sufficient.

244. **Decide for me, let me override.** Opinionated defaults are features. Escape hatches are requirements. Strong opinions, loosely held.

255. **Fight uncertainty.** Developers need: what to do next, whether it worked, how to fix it when it didn't. Every error meets the agent-ready error contract, so an agent can repair it or escalate precisely without reading the source.

266. **Show code in context.** Hello world is a lie. Show real auth, real error handling, real deployment. Solve 100% of the problem.

277. **Speed is a feature.** Iteration speed is everything. Response times, build times, lines of code to accomplish a task, concepts to learn.

288. **Create magical moments.** What would feel like magic? Stripe's instant API response. Vercel's push-to-deploy. Find yours and make it the first thing developers experience.

299. **Agents are users too.** Non-interactive by default, structured output, layered \`--help\`, and errors written as the agent's next prompt.

31## The Seven DX Characteristics

34|---|---------------|---------------|---------------|

43## Cognitive Patterns — How Great DX Leaders Think

45Internalize these; don't enumerate them.

471. **Chef-for-chefs** — Your users build products for a living. The bar is higher because they notice everything.

482. **First five minutes obsession** — New dev arrives. Clock starts. Can they hello-world without docs, sales, or credit card?

493. **Error message empathy** — Every error is pain, and an agent often hits it first. Would an agent that hit this unattended know the safe next command, or exactly what to ask a human for?

504. **Escape hatch awareness** — Every default needs an override. No escape hatch = no trust = no adoption at scale.

515. **Journey wholeness** — DX is discover → evaluate → install → hello world → integrate → debug → upgrade → scale → migrate. Every gap = a lost dev.

526. **Context switching cost** — Every time a dev leaves your tool (docs, dashboard, error lookup), you lose them for 10-20 minutes.

537. **Upgrade fear** — Will this break my production app? Clear changelogs, migration guides, codemods, deprecation warnings. Upgrades should be boring.

548. **SDK completeness** — If devs write their own HTTP wrapper, you failed. If the SDK works in 4 of 5 languages, the fifth community hates you.

559. **Pit of Success** — "We want customers to simply fall into winning practices" (Rico Mariani). Make the right thing easy, the wrong thing hard.

5610. **Progressive disclosure** — Simple case is production-ready, not a toy. Complex case uses the same API. SwiftUI: \\\`Button("Save") { save() }\\\` → full customization, same API.

58## DX Scoring Rubric (0-10 calibration)

60| Score | Meaning |

61|-------|---------|

62| 9-10 | Best-in-class. Stripe/Vercel tier. Developers rave about it. |

63| 7-8 | Good. Developers can use it without frustration. Minor gaps. |

64| 5-6 | Acceptable. Works but with friction. Developers tolerate it. |

65| 3-4 | Poor. Developers complain. Adoption suffers. |

66| 1-2 | Broken. Developers abandon after first attempt. |

67| 0 | Not addressed. No thought given to this dimension. |

69**The gap method:** For each score, explain what a 10 looks like for THIS product. Then fix toward 10.

71## TTHW Benchmarks (Time to Hello World)

73| Tier | Time | Adoption Impact |

74|------|------|-----------------|

75| Champion | < 2 min | 3-4x higher adoption |

76| Competitive | 2-5 min | Baseline |

77| Needs Work | 5-10 min | Significant drop-off |

78| Red Flag | > 10 min | 50-70% abandon |

80## Hall of Fame Reference

82During each review pass, load the relevant section from:

83\\\`${hallOfFamePath}\\\`

85Read ONLY the section for the current pass (e.g., "## Pass 1" for Getting Started).

86Do NOT read the entire file at once. This keeps context focused.`;

87}

89/** {{DX_ERROR_COMPACT}}: the contract's compact form for reviewer prompts. */

90export function generateDxErrorCompact(_ctx: TemplateContext): string {

91 return DX_ERROR_COMPACT;

92}

94/** {{DX_ERROR_ITEMS}}: the contract's item names, for steps that load the full text lazily. */

95export function generateDxErrorItems(_ctx: TemplateContext): string {

96 return DX_ERROR_ITEMS.join(', ');

97}