Guided/Quick Setup Convention — unify interactive vs default resolution across setup skills

[rucka]

Story Statement

As a pair contributor authoring or extending a setup-oriented skill
I want a single documented Guided/Quick Setup Convention — every setup skill exposes the same guided (asks questions) vs. quick (accepts sensible defaults) duality, resolved the same way
So that the pattern stops being reinvented ad hoc per skill, and Quickstart (story #[TBD-quickstart]) has a real convention to compose instead of its own bespoke mechanism

Where: new KB guideline (knowledge/guidelines/collaboration/ or technical-standards/ — final placement decided in refinement) + adoption by pair-capability-package's existing --interactive flag and the assess-* family's Resolution Cascade pattern

Epic Context

Parent Epic: Skill marketplace + Quickstart + external KB scaffold #213
Status: Refined
Priority: P0 (Must-Have — Quickstart depends on this existing first)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given the new guideline
   When it is published
   Then it documents the convention generically: any setup-oriented skill/command exposes a guided mode (asks questions one at a time, best UX for first-time/unfamiliar setup) and a quick mode (accepts KB-sensible defaults in one shot, best for CI/scripting/experienced users), with a single, consistent way to select between them

2. Given the two pre-existing, independently-evolved implementations of this pattern already in this repo
   When the guideline is written
   Then it explicitly cites both as the reference precedent: pair-capability-package's --interactive boolean flag + resolveDefaults() cascade (CLI flags > package.json > git config > saved preferences), and the assess-* skill family's Resolution Cascade (Path A: Argument Override > Path B: Existing/Adoption > Path C: Full Assessment) — the guideline names the shared shape both already implement, it does not invent a third mechanism

3. Given a skill or CLI command that already implements one of these two patterns
   When this story ships
   Then neither pair-capability-package nor any assess-* skill is rewritten — the guideline documents the existing convention for future adopters; retrofitting past implementations to a unified vocabulary is explicitly out of scope

4. Given a future setup skill (starting with Quickstart, story #[TBD-quickstart])
   When it is authored
   Then it adopts this convention directly rather than designing its own guided/quick duality from scratch

Business Rules

• Convention over configuration: guided mode is the safer default for standalone/first-time invocation; quick mode requires an explicit signal (a flag, an argument, or a detected non-interactive environment) — never the reverse
• This is a documentation and naming convention story, not a refactor: existing implementations (pair-capability-package, assess-*) are cited as precedent, not modified
• The guideline must name the convention precisely enough that a future skill author can look it up and apply it without re-deriving the pattern from the two existing examples

Edge Cases and Error Handling

• A future skill needs a third mode (e.g., partially-guided): the guideline documents the two-mode convention as the default shape; a skill with a genuine need for more modes documents its deviation explicitly rather than silently diverging
• Non-interactive environment detected but guided mode requested: the guideline's resolution order follows the same Argument > Adoption > KB default-style precedence already established elsewhere in this KB — an explicit environment signal (e.g., no TTY) can override a requested guided mode with a warning, never silently

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Guideline follows KB writing conventions (markdownlint green, reading-budget respected)
• Code review completed and approved
• Documentation updated — docs site (setup/customization section, cross-linked from the CLI reference)

Quality Assurance

• Cross-check: the guideline's description of pair-capability-package's --interactive flag and the assess-* Resolution Cascade matches the real, current code exactly (no invented behavior)

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 2 (S)
Confidence Level: High
Sizing Justification: pure documentation of an already-existing, already-working pattern — no new code, no retrofit; the work is naming and writing down what's already true

Sprint Capacity Validation

Sprint Fit Assessment: yes, single sprint
Total Effort Assessment: fits — Yes

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: none
Dependent Stories: Quickstart (story #[TBD-quickstart]) — composes this convention directly as its guided/quick resolution mechanism

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: manual cross-check of the guideline's factual claims against apps/pair-cli/src/commands/package/parser.ts/interactive.ts and any assess-* SKILL.md's Resolution Cascade section
Test Data Requirements: none — verified directly against the real source

Notes and Additional Context

Refinement Session Insights: surfaced during design discussion for the Quickstart story — the "poc profile" framing from the original epic triage was set aside in favor of this more general, precedent-grounded convention; confirmed as its own story (not folded into Quickstart) since the pattern is already duplicated in 2 places in the codebase and a single unifying guideline prevents a third, Quickstart-specific reinvention.
Documentation Links: Requirements R9.1 (Quickstart) · originating design discussion in this session, 2026-07-11

Technical Analysis

Implementation Approach

Technical Strategy: pure KB guideline documenting an existing pattern; no runtime code changes to pair-capability-package or any assess-* skill
Key Components: new guideline document; cross-links from pair-capability-package's and assess-*'s own SKILL.md/code comments (optional, non-blocking) back to the guideline
Integration Points: consumed by Quickstart (story #[TBD-quickstart]) as its resolution mechanism

Technical Requirements

• Every factual claim about existing code (--interactive flag behavior, resolveDefaults() cascade order, assess-* Path A/B/C) must be verified against the real files, not written from memory

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Guideline drifts from actual pair-capability-package/assess-* behavior if either changes later without updating the guideline	Low	Medium	Guideline explicitly names the two files/patterns it documents, making drift greppable in future reviews

Task Breakdown

Checklist

• T1 — Verify and document pair-capability-package's --interactive/resolveDefaults() mechanism as reference precedent
• T2 — Verify and document the assess-* Resolution Cascade (Path A/B/C) as reference precedent
• T3 — Write the generic Guided/Quick Setup Convention (naming, resolution order, when each mode applies) + docs site page

Dependency Graph

T1 → T3; T2 → T3

AC Coverage

Task	AC1	AC2	AC3	AC4
T1		✓	✓
T2		✓	✓
T3	✓			✓