[PM-33571] llm: Add requirements refinement and planning skills #2445
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| --- | ||
| description: Plan implementation for a Bitwarden iOS Jira ticket or task description. Fetches requirements, performs gap analysis, designs the implementation approach, and saves a design doc to .claude/outputs/plans/. | ||
| argument-hint: <PM-XXXXX ticket ID or task description> | ||
| --- | ||
|
|
||
| # Plan iOS Work: $ARGUMENTS | ||
|
|
||
| ## Phase 1: Ingest Requirements | ||
|
|
||
| If `$ARGUMENTS` looks like a Jira ticket ID (e.g., `PM-12345` or `BWA-456`): | ||
| - Fetch the ticket: `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue` | ||
| - Fetch comments for context: `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments` | ||
|
|
||
| If `$ARGUMENTS` is a description, use it directly as the requirements source. | ||
|
|
||
| ## Phase 2: Refine Requirements | ||
|
|
||
| Invoke the `refining-ios-requirements` skill to: | ||
| - Extract structured requirements and acceptance criteria | ||
| - Perform gap analysis (error states, edge cases, extensions, accessibility) | ||
| - Map to iOS domain (see `Docs/Architecture.md` Architecture Structure for domain list) | ||
|
|
||
| **Pause here**: Present requirements to user and confirm accuracy before proceeding. | ||
|
|
||
| ## Phase 3: Plan Implementation | ||
|
|
||
| Once requirements are confirmed, invoke the `planning-ios-implementation` skill to: | ||
| - Classify the change type | ||
| - Explore existing similar patterns in the codebase | ||
| - List all files to create/modify with domain placement | ||
| - Order implementation into dependency-ordered phases | ||
| - Assess risks (security, extensions, multi-account, SDK) | ||
|
|
||
| ## Phase 4: Save Design Doc | ||
|
|
||
| Save the complete plan to `.claude/outputs/plans/<ticket-id>.md`. | ||
|
|
||
| **Final output**: "Plan saved to `.claude/outputs/plans/<ticket-id>.md`. Ready to implement with `/work-on-ios <ticket-id>`." | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| --- | ||
| name: planning-ios-implementation | ||
| description: Plan implementation, design an approach, or create an architecture plan for a Bitwarden iOS feature. Use when asked to "plan implementation", "design approach", "architecture plan", "how should I implement", "what files do I need", or to create a design doc before writing code. | ||
| --- | ||
|
|
||
| # Planning iOS Implementation | ||
|
|
||
| Use this skill to design a complete implementation plan before writing code. Output is saved as a design document. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Requirements must be clear. If not, invoke `refining-ios-requirements` first. | ||
| - Read `Docs/Architecture.md` before proceeding — it is the authoritative source for all patterns. | ||
|
|
||
|
Comment on lines
+10
to
+14
Member
There was a problem hiding this comment. 🤔 Should it also read the
Contributor
Author
There was a problem hiding this comment. I've not run into that as an issue on the Android side of things. I would wait until we see Claude exhibiting undesirable behavior before preemptively telling it to consume more context. If that turns out to be needed, I would prefer a simple directive like, "consider testability while designing implementation." before having it re-ingest the entire |
||
| ## Step 1: Classify the Change | ||
|
|
||
| Determine the change type to guide scope and planning depth: | ||
|
|
||
| | Type | Description | Typical Scope | | ||
| |------|-------------|---------------| | ||
| | **New Feature** | Entirely new functionality, screens, or flows | New files + modifications, multi-phase | | ||
| | **Enhancement** | Extending existing feature with new capabilities | Mostly modifications, 1-2 phases | | ||
| | **Bug Fix** | Correcting incorrect behavior | Targeted modifications, single phase | | ||
| | **Refactoring** | Restructuring without behavior change | Modifications only, migration-aware | | ||
| | **Infrastructure** | Build, CI, tooling, or dependency changes | Config files, minimal code changes | | ||
|
|
||
| State the classification and rationale before proceeding. | ||
|
|
||
| ## Step 2: Explore Existing Patterns | ||
|
|
||
| Search the codebase for similar existing implementations to follow: | ||
| - Find a similar existing feature in the same domain | ||
| - Identify which services/repositories it uses | ||
| - Note how its Coordinator, Processor, and View are structured | ||
| - Check if `BitwardenKit/UI/` has reusable components for the new UI | ||
|
|
||
| ## Step 3: List Files to Create/Modify | ||
|
|
||
| For each file, specify path, action (create/modify), domain placement, and purpose. Group by layer: | ||
|
|
||
| ``` | ||
| ### New Files (Create) | ||
|
|
||
| #### Core Layer | ||
| - `BitwardenShared/Core/<Domain>/<Feature>/Services/<Feature>Service.swift` | ||
| - Protocol + Default<Feature>Service + Has<Feature>Service | ||
|
|
||
| #### UI Layer | ||
| - `BitwardenShared/UI/<Domain>/<Feature>/<Feature>Coordinator.swift` | ||
| - `BitwardenShared/UI/<Domain>/<Feature>/<Feature>Processor.swift` | ||
| - `BitwardenShared/UI/<Domain>/<Feature>/<Feature>State.swift` | ||
| - `BitwardenShared/UI/<Domain>/<Feature>/<Feature>Action.swift` | ||
| - `BitwardenShared/UI/<Domain>/<Feature>/<Feature>Effect.swift` | ||
| - `BitwardenShared/UI/<Domain>/<Feature>/<Feature>View.swift` | ||
|
|
||
| #### Tests (co-located with implementation) | ||
| - `BitwardenShared/UI/<Domain>/<Feature>/<Feature>ProcessorTests.swift` | ||
| - `BitwardenShared/Core/<Domain>/<Feature>/Services/<Feature>ServiceTests.swift` | ||
|
|
||
| ### Modified Files | ||
| - `BitwardenShared/Core/Platform/Services/ServiceContainer.swift` — Add new service | ||
| - `<Existing>Coordinator.swift` — Add new route | ||
| ``` | ||
|
|
||
| ## Step 4: Dependency-Ordered Implementation Phases | ||
|
|
||
| Order phases so each builds on the previous: | ||
|
|
||
| ``` | ||
| ### Phase 1: Data / Core Layer | ||
| Models, CoreData entities (if needed), service protocols, repository protocols | ||
|
|
||
| ### Phase 2: Service/Repository Implementations | ||
| Default<Name>Service/Repository — business logic, SDK calls, network | ||
|
|
||
| ### Phase 3: DI Wiring | ||
| ServiceContainer extensions, Has* protocol additions | ||
|
|
||
| ### Phase 4: Processor + State | ||
| StateProcessor subclass, State struct, Action enum, Effect enum | ||
|
|
||
| ### Phase 5: View + Coordinator | ||
| SwiftUI View with store.binding, Coordinator with routes, navigation wiring | ||
|
|
||
| ### Phase 6: Tests | ||
| ProcessorTests (action/effect paths), ServiceTests (business logic), ViewTests (snapshots if UI) | ||
| ``` | ||
|
|
||
| ## Step 5: Risk Assessment | ||
|
|
||
| Identify risks and mitigations: | ||
| - **Security**: Does this touch vault data, auth tokens, or Keychain? → Security review required | ||
| - **Extensions**: Does this affect AutoFill/Action/Share extensions? → Memory limit check needed | ||
| - **Multi-account**: Does this need per-account isolation? → CoreData userId scoping | ||
| - **SDK dependency**: Does this require BitwardenSdk changes? → Coordinate with SDK team | ||
|
|
||
| ## Step 6: Save Design Document | ||
|
|
||
| Save the plan to `.claude/outputs/plans/<ticket-id>.md`. | ||
|
|
||
| ## Confirm Before Proceeding | ||
|
|
||
| Present the plan to the user and ask: "Here is the implementation plan. Should I proceed with implementation?" | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| --- | ||
| name: refining-ios-requirements | ||
| description: Refine requirements, analyze a ticket, perform gap analysis, or clarify what a Jira/Confluence ticket is asking before coding in Bitwarden iOS. Use when asked to "refine requirements", "analyze ticket", "gap analysis", "clarify ticket", "what does this ticket mean", or to understand scope before implementation begins. | ||
| --- | ||
|
|
||
| # Refining iOS Requirements | ||
|
|
||
| Use this skill to analyze a Jira or Confluence ticket and produce structured, implementation-ready requirements before writing any code. | ||
|
|
||
| ## Step 1: Ingest the Ticket | ||
|
|
||
| If a ticket ID or URL is provided, fetch it via MCP: | ||
| - Use `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue` for Jira tickets | ||
| - Use `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments` for additional context | ||
| - Use `mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page` for Confluence specs | ||
|
|
||
| If no ticket is provided, ask for a description of the requirements. | ||
|
|
||
| ## Step 2: Extract Requirements | ||
|
|
||
| Identify and list: | ||
| 1. **Core functionality**: What must this feature/fix do? | ||
| 2. **Acceptance criteria**: What defines "done"? | ||
| 3. **Out of scope**: What is explicitly excluded? | ||
| 4. **Dependencies**: Other tickets, SDK changes, API endpoints needed? | ||
|
|
||
| ## Step 3: Gap Analysis | ||
|
|
||
| Identify unstated requirements the ticket may have missed: | ||
|
|
||
| **Error states** | ||
| - Network errors, timeout, server errors | ||
| - Validation failures, empty states | ||
| - SDK errors (encryption/decryption failures) | ||
|
|
||
| **Edge cases** | ||
| - Multi-account scenarios (up to 5 accounts) | ||
|
Member
There was a problem hiding this comment. ⛏️ Is it actually needed to state there are a maximum of 5 accounts here?
Contributor
Author
There was a problem hiding this comment. I don't think it hurts. It's not obvious without exploring the code but could impact planning and it's not token heavy. |
||
| - Account switching during the operation | ||
| - Locked vs unlocked vault state | ||
| - Empty vault / first-time user | ||
|
|
||
| **Platform concerns** | ||
| - App extension impact (AutoFill, Action, Share — memory limits apply) | ||
| - watchOS companion impact (if vault data is involved, especially TOTP data) | ||
| - Offline mode behavior | ||
|
|
||
| **Accessibility** | ||
| - VoiceOver labels for new UI elements | ||
| - Dynamic Type support | ||
| - Keyboard navigation | ||
|
|
||
| ## Step 4: Map to iOS Domain | ||
|
|
||
| Determine which Bitwarden iOS domain(s) are involved. Read `Docs/Architecture.md` (Architecture Structure section) for the canonical domain list and descriptions. | ||
|
|
||
| Determine which app(s) are affected: | ||
| - **BitwardenShared**: Password Manager | ||
| - **AuthenticatorShared**: Authenticator | ||
| - **Both**: If the feature touches shared components | ||
|
|
||
| ## Step 5: Output Structured Requirements | ||
|
|
||
| ```markdown | ||
| ## Ticket: [PM-XXXXX] — [Title] | ||
|
|
||
| ### What | ||
| [1-2 sentence summary of what needs to be built] | ||
|
|
||
| ### Why | ||
| [Business/user reason for the change] | ||
|
|
||
| ### Acceptance Criteria | ||
| 1. [Criterion 1] | ||
| 2. [Criterion 2] | ||
|
|
||
| ### Gap Analysis | ||
| **Unstated requirements identified:** | ||
| - [ ] Error state: [description] | ||
| - [ ] Edge case: [description] | ||
| - [ ] Platform concern: [description] | ||
|
|
||
| **Clarifying questions (if any):** | ||
| 1. [Question for product/design] | ||
|
|
||
| ### Scope | ||
| - **Domain**: [from Architecture Structure domain list] | ||
| - **App(s)**: [Password Manager / Authenticator / Both] | ||
| - **Extensions affected**: [AutoFill / Action / Share / Watch / None] | ||
| - **Out of scope**: [explicit exclusions] | ||
| ``` | ||
|
|
||
| ## Confirm Before Proceeding | ||
|
|
||
| Present the structured requirements to the user and ask: "Are these requirements accurate? Should I proceed with planning the implementation?" | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
❓ Maybe it's defined in another place but which would be the possible change types? Or is it just general for the LLM to figure out?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Classifying is a step in the
planning-ios-implementationskill. This is "priming" Claude so it knows what the skill will be doing. I see thatplanning-ios-implementationdoesn't mirror the Android version, though, so I'll fix that up.