sample-app-design

name	sample-app-design
description	Spec a sample app or SDK quickstart that demonstrates the real value path as production-grade, runnable code — it runs from a clean checkout, handles errors, pins versions, and has no hardcoded secrets. Use when designing or reviewing sample code that developers will copy verbatim.

Skill: Sample-app design

Design sample code that a developer can copy into production without learning a bad habit. Sample code is production code — it's copied verbatim into real codebases.

When to use

• You need a sample app or SDK quickstart to show off the product's value path.
• A snippet/sample is about to be published and needs a production-grade review.
• A toy example is setting developers up for a cliff when they hit the hard parts.

Procedure

1. Pick the value path, not a toy. The sample demonstrates the real reason a developer would use the product — including the parts that are genuinely hard. Hiding the hard parts is a future support ticket.
2. Scope it to runnable. It compiles and runs from a clean checkout with a documented, minimal setup. If it doesn't run from clean, it isn't done.
3. Handle errors. Show the real failure modes (rate limits, auth expiry, bad input) and the correct handling — not a happy-path-only snippet that breaks the moment reality intrudes.
4. Secure by default. No hardcoded secrets — env vars or a secret manager, never a literal key. Teach the secure pattern, because everyone who copies it inherits it. Route auth/secret deep dives to security-engineering.
5. Pin versions so the sample doesn't rot when a dependency ships a breaking change.
6. Mark any product friction for developer-advocate to file — don't bury it in prose. Capture the spec in the sample-app-spec template.

Output

A sample-app spec (value path, runnable scope, error handling, secure patterns, pinned versions) ready for the content-engineer to build.

Anti-patterns (the hook flags these)

• A sample with a hardcoded secret/API key (teaches a vulnerability at scale).
• A sample that swallows errors (empty catch / ignored failure).
• A toy that hides the hard parts and sets up a cliff.