design-interview

Elicits design facts and formalizes guiding principles into a repo's DESIGN.md.

4|Updated Jul 11, 2026
One-click install
npx skills add https://github.com/jmgirard/cairn --skill design-interview-jmgirard
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: design-interview
Source: https://github.com/jmgirard/cairn/tree/main/skills/design-interview
Command: npx skills add https://github.com/jmgirard/cairn --skill design-interview-jmgirard

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code alone cannot reveal why a repository was built the way it was — who it serves, where its contract boundary lies, or which principles are inviolable. This Skill runs a structured two-phase interview that captures that intent from the maintainer and writes it into cairn/DESIGN.md, so future sessions and contributors can act on documented design rationale instead of guesswork. ## Core Features & Use Cases - Phase 1 — Facts: Batched question rounds elicit intent the code cannot show (audience, contract boundary, platform commitments, API-stability posture), with every option grounded in cited repo evidence and proto-principles banked rather than decided. - Phase 2 — Principles: Formalizes banked candidates plus principles mined from git history and domain constraints, classifying each as IP (inviolable) or GP (guiding) with stress tests against Phase-1 decisions, then writes them to DESIGN.md with stable numbering. - Migration ingestion: Preserved numbered-principles files (e.g. PRINCIPLES.md cited in code) are ingested as candidates with a recorded old-#N to new-id lineage map, without editing the preserved file. - Use Case: After scaffolding a repo with /cairn-init, run the interview to turn a thin DESIGN.md into a documented purpose, contract boundary, and numbered principle set that later milestone planning and reviews can enforce. ## Quick Start Ask the assistant to run a design interview to articulate this repo's purpose, contract boundary, and guiding principles in cairn/DESIGN.md.

Frequently Asked Questions about design-interview

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document a repo's design principles with Claude Code?

Run the design-interview skill, which asks batched questions about intent the code cannot show, then formalizes the answers into numbered IP (inviolable) and GP (guiding) principles written to cairn/DESIGN.md.

What is the difference between the two interview phases?

Phase 1 elicits facts — audience, contract boundary, platform and API-stability commitments — and only banks proto-principles. Phase 2 formalizes those candidates, stress-tests them against Phase-1 decisions, and writes the settled principles to DESIGN.md.

Can I run a design interview on someone else's repository?

Yes. When cairn/PROFILE.md declares guest collaboration mode, the interview captures your understanding of the maintainers' intent, and every principle written is marked provisional until the upstream maintainers correct it.

What happens to an existing PRINCIPLES.md cited in code?

The preserved file is never edited or renumbered. Each numbered principle enters Phase 2 as a candidate, receives an explicit disposition, and a lineage map from old #N to new IP/GP ids is recorded in DESIGN.md.

When should I not run the design interview?

Do not run it before scaffolding: if the repo has no cairn/ directory, the skill stops and routes you to /cairn-init first. It also performs no code edits, so it cannot replace implementation milestones.