SLT.BETA.020 – Setup Questionnaire (guided configuration) #82
Description
[SLT.BETA.020] Setup Questionnaire (guided configuration)
Overview
Deliver a guided configuration experience that asks targeted questions about hosting and workflow preferences, then generates tailored Shiplog policy, trust, and CI recommendations.
References & Assets
- Figma / Design: N/A
- Product Spec (Notion / Confluence): N/A
- Related Issues / PRs: SLT.BETA.019, SLT.BETA.021
- Feature Flags / Experiments: N/A
- Other Assets: docs/features/config.md
User Story
As a team lead onboarding Shiplog, I want an interactive questionnaire that produces host-aware configuration, so that our team gets secure defaults without reading every doc upfront.
Acceptance Criteria
- TTY wizard asks questions covering host, enforcement, signing mode, threshold, auto-push, and CI preferences
- Non-interactive mode consumes answers from JSON or CLI flags
- Output includes recommended policy, trust bootstrap steps, and CI/ruleset guidance
- Wizard summaries are exportable for review or CI execution
- Dockerized tests cover representative answer flows
Definition of Done
Wizard integrated into git shiplog config, documentation updated, and automated tests validate primary flows and outputs.
Scope
In-Scope
- Questionnaire design and mapping to configuration outputs
- CLI implementation with TTY and non-interactive modes
- Documentation and examples
Out-of-Scope
- GUI wizard implementations
- Automatic repo modification beyond existing config apply path
Deliverables
- Est. Lines of Code: ~300
- Est. Blast Radius:
scripts/config, docs, tests
Implementation Details
High-Level Approach
Build a question graph driving configuration templates, reuse existing plan/apply mechanics, and ensure outputs cover policy, trust, and enforcement guidance.
Affected Areas
- scripts/config
- docs/features/config.md
- README.md
- tests/config_wizard.bats
Implementation Steps
- Finalize questionnaire flows and outcomes
- Implement interactive prompts with fallback to plain text
- Support non-interactive answers via JSON file and flags
- Generate policy/trust/CI recommendations based on answers
- Update docs and add tests
Test Plan
Happy Path
- Wizard run for GitHub SaaS outputs branch namespace + ruleset guidance
- Non-interactive run produces matching plan JSON
Edge Cases
- Unsupported host triggers helpful guidance
- Re-running wizard respects previous answers when desired
Failure Cases
- Invalid answer schema surfaces descriptive validation errors
Monitoring & Success Metrics
- Wizard summary logs include chosen options and follow-up tasks
QA Sign-off Matrix
| Environment | Surface | Owner | Status | Notes |
|---|---|---|---|---|
| Local Docker | CLI | TBD | Pending | Validated via make test |
Requirements
Hard Requirements
- Generated outputs must align with hosting enforcement matrix
Soft Requirements
- Provide copy/paste snippets users can share in PRs
Runtime Requirements
- Works in non-interactive CI environments via flags/JSON
Dependencies & Approvals
- Docs review for README and config guide updates
- Security review for default trust recommendations
Production Notes
Priority: 4 / 5
High value onboarding improvement (P1 roadmap item).
Complexity: 4 / 5
Complex branching questionnaire with multiple output types.
Estimate: 28 - 40 hours
Covers design, implementation, docs, and thorough testing.
Risk & Rollback
- Primary Risks: Incorrect recommendations leading to insecure defaults
- Mitigations: Validate outputs against hosting matrix, review by maintainers
- Rollback / Kill Switch: Hide behind feature flag until validated
Additional Notes
Depends on hosting guidance (SLT.BETA.019) landing first.