ai-playbook 1.0.0

package/prompts/support/README.md

@@ -0,0 +1,154 @@
+# Support Prompts
+
+Reusable prompts for customer support and issue resolution.
+
+## Available Prompts
+
+### [resolve-issue.md](resolve-issue.md)
+
+**Use when:** Helping customers resolve issues
+
+**Covers:**
+- Issue description
+- Customer context
+- Troubleshooting info
+- What customer tried
+- System status
+- Solution/resolution
+
+**Good for:**
+- Customer support
+- Technical troubleshooting
+- Help documentation
+- Issue resolution
+
+## Using Support Prompts
+
+### Support Process
+
+1. **Listen** - Understand customer issue
+2. **Gather info** - Environment, steps, errors
+3. **Troubleshoot** - Ask diagnostic questions
+4. **Root cause** - Identify underlying issue
+5. **Solution** - Provide resolution
+6. **Verify** - Confirm issue is fixed
+7. **Prevent** - Advise on prevention
+8. **Document** - Create help article if needed
+
+## What Gets Delivered
+
+✓ Issue understood  
+✓ Root cause identified  
+✓ Solution provided  
+✓ Clear instructions  
+✓ Follow-up plan  
+✓ Prevention advice  
+
+## Quality Gates
+
+Support must provide:
+
+✓ **Understanding** - Issue fully understood  
+✓ **Solution** - Fix that works  
+✓ **Clarity** - Instructions easy to follow  
+✓ **Empathy** - Respectful, patient tone  
+✓ **Documentation** - Help article created  
+
+## Support Checklist
+
+- [ ] Understand the issue
+- [ ] Gather all information
+- [ ] Identify root cause
+- [ ] Provide solution
+- [ ] Verify it works
+- [ ] Clear instructions given
+- [ ] Prevention advice provided
+- [ ] Follow-up scheduled
+- [ ] Help doc created
+- [ ] Customer satisfied
+
+## Communication Guidelines
+
+### Do's
+
+- ✓ Ask clarifying questions
+- ✓ Explain in simple terms
+- ✓ Step-by-step instructions
+- ✓ Show understanding
+- ✓ Take accountability
+- ✓ Follow up
+- ✓ Document for future
+
+### Don'ts
+
+- ✗ Use technical jargon
+- ✗ Blame the customer
+- ✗ Rush to judgment
+- ✗ Assume too much
+- ✗ Ignore follow-ups
+- ✗ Create one-time fixes
+- ✗ Lack empathy
+
+## Issue Categories
+
+### Technical Issues
+- Bug reproduction
+- Error diagnosis
+- Configuration help
+- Integration support
+
+### Account Issues
+- Login problems
+- Password resets
+- Billing questions
+- Access issues
+
+### Usage Questions
+- Feature explanation
+- Best practices
+- Workflow help
+- Documentation
+
+## Escalation Criteria
+
+Escalate to engineering when:
+- Bug in product
+- Data loss/corruption
+- Security concern
+- Feature request
+- Complex investigation needed
+
+## Documentation
+
+Create help articles for:
+- Common issues
+- Workarounds
+- Setup guides
+- Troubleshooting steps
+- FAQ entries
+
+## Best Practices
+
+### Effective Support
+
+- Listen first, suggest second
+- Validate customer concerns
+- Be transparent about issues
+- Provide options
+- Follow up proactively
+- Document thoroughly
+- Learn from issues
+- Improve processes
+
+### Response Time
+
+- Critical issues: < 30 minutes
+- High priority: < 1 hour
+- Medium: < 4 hours
+- Low: < 24 hours
+
+## Related Documentation
+
+- See `../README.md` for overview
+- Check hooks/ for troubleshooting automation
+- Review commands/ for self-service options

package/prompts/support/resolve-issue.md

@@ -0,0 +1,124 @@
+# Resolve Support Issue Prompt
+
+**Role:** Support  
+**Type:** Customer Support Resolution  
+**Context Needed:** Issue description, customer context, logs, system status
+
+## Template
+
+```
+Help customer resolve: [Issue Title]
+
+## Customer Issue
+[What the customer reports]
+
+## Customer Context
+- Account: [Account/user info]
+- Usage: [How they use it]
+- Affected since: [When it started]
+- Impact: [What's blocked]
+
+## Troubleshooting Info
+- Logs: [Relevant logs]
+- Error message: [Exact error]
+- Environment: [Browser/OS/version]
+- Steps to reproduce: [Steps]
+
+## What I've Tried
+[What customer already tried]
+
+## System Status
+[Any known issues, deployments, etc.]
+
+## Expected Deliverables
+- Root cause identified
+- Solution/workaround provided
+- Next steps for customer
+- Prevention advice
+- Documentation (if needed)
+```
+
+## When to Use
+
+- Responding to customer issues
+- Troubleshooting problems
+- Providing technical support
+- Creating help documentation
+- Resolving service issues
+
+## Required Context
+
+- Complete issue description
+- Steps to reproduce
+- Customer environment details
+- Error messages/logs
+- What customer tried
+- Expected behavior
+
+## Expected Output
+
+- ✓ Issue understood
+- ✓ Root cause found
+- ✓ Solution provided
+- ✓ Clear instructions
+- ✓ Follow-up plan
+- ✓ Preventive advice
+
+## Quality Gates
+
+```
+Understanding:
+  ✓ Issue fully understood
+  ✓ Customer context clear
+  ✓ All details gathered
+
+Resolution:
+  ✓ Solution works
+  ✓ Instructions clear
+  ✓ Expected outcome stated
+
+Communication:
+  ✓ Language simple
+  ✓ Non-technical jargon
+  ✓ Empathetic tone
+```
+
+## Example Usage
+
+```
+Help customer: Cannot export data
+
+## Customer Issue
+Customer cannot export CSV of their data. Button greyed out.
+
+## Customer Context
+- Account: Enterprise plan
+- Usage: 2 years
+- Affected since: Yesterday after upgrade
+- Impact: Weekly reporting blocked
+
+## Troubleshooting Info
+Error: "Export feature unavailable"
+Browser: Chrome 120 on macOS
+Steps: Click Settings → Export → CSV
+
+## What I've Tried
+- Refreshed page
+- Cleared cache
+- Different browser
+
+## System Status
+Deployed new export feature yesterday
+Some users reporting issues with large datasets
+```
+
+## Tips
+
+- Ask clarifying questions
+- Gather all information first
+- Verify understanding
+- Provide step-by-step instructions
+- Use screenshots/videos
+- Explain the why
+- Prevent future issues
+- Be patient and empathetic

package/roles/README.md

@@ -0,0 +1,6 @@
+# Roles
+
+Use this folder for role operating models.
+
+Each role should explain responsibilities, decision posture, workflows,
+triggers, skill routing, checklists, and examples.

package/roles/design-architect/README.md

@@ -0,0 +1,98 @@
+# Design Architect Role
+
+This packet defines how an AI-supported design architect should shape usable,
+accessible, coherent product experiences from early framing through developer
+handoff. It focuses on design systems, interface structure, interaction models,
+visual hierarchy, and evidence-based design decisions.
+
+## Contract
+
+Use this role when the work involves:
+
+- Designing or redesigning product screens, flows, navigation, or layouts.
+- Creating design systems, component libraries, tokens, or pattern guidance.
+- Reviewing UI quality, accessibility, usability, or visual consistency.
+- Producing wireframes, design specs, prototypes, or implementation-ready notes.
+- Translating product goals and user needs into structured interface decisions.
+
+The role must always preserve these priorities:
+
+1. User clarity.
+2. Accessibility.
+3. Consistency.
+4. Technical feasibility.
+5. Scalability.
+6. Visual quality.
+7. Clear handoff.
+
+## Files
+
+| File or folder | Meaning |
+| --- | --- |
+| `role.md` | Core behavior, mindset, constraints, and success criteria. |
+| `responsibilities.md` | Ownership areas for design strategy, systems, review, and handoff. |
+| `workflow.md` | Canonical lifecycle from intake through validation and delivery. |
+| `triggers.md` | Situations that activate this role and the immediate response pattern. |
+| `skill-map.md` | Skills to load or reference for common design architecture work. |
+| `checklists.md` | Reusable quality gates for screens, systems, accessibility, and handoff. |
+| `examples.md` | Example decisions, reviews, artifacts, and handoff notes. |
+| `accessibility/` | Inclusive design and WCAG-oriented design checks. |
+| `component-library/` | Component inventory, variants, states, and governance. |
+| `design-system/` | Tokens, patterns, foundations, documentation, and adoption. |
+| `figma/` | Figma file structure, naming, components, and handoff hygiene. |
+| `responsive/` | Breakpoints, adaptive layouts, input modes, and device checks. |
+| `ui/` | Visual design, layout, hierarchy, typography, color, and polish. |
+| `usability/` | Task success, friction reduction, research, and validation. |
+| `ux/` | Flows, information architecture, interaction models, and journey design. |
+| `wireframes/` | Low-fidelity structure, content priority, and flow exploration. |
+| `examples/` | Larger scenario templates and example design artifacts. |
+
+## Loading Order
+
+When applying this role, load files in this order:
+
+1. `role.md` to establish behavior and constraints.
+2. `triggers.md` if the request type is ambiguous.
+3. `workflow.md` for the lifecycle stage.
+4. `skill-map.md` to select supporting skills.
+5. `checklists.md` for execution gates.
+6. Topic folders such as `design-system/`, `ui/`, `ux/`, `accessibility/`,
+   `responsive/`, `component-library/`, `figma/`, or `wireframes/` when the
+   task touches that area.
+7. `examples.md` when artifact shape or review style needs concrete reference.
+
+For product work, also load `context/communication.md`, relevant project or
+brand context, and frontend engineering guidance when implementation constraints
+matter.
+
+## Topic Folders
+
+Each topic folder follows the same mini-packet shape:
+
+- `README.md` explains scope, standards, and related folders.
+- `checklists.md` lists design, review, validation, and handoff gates.
+- `examples.md` provides starter examples or templates.
+
+Load only the topic packets that match the current task. A design system request
+might load `design-system/`, `component-library/`, `accessibility/`, and
+`figma/`; a mobile redesign might load `ux/`, `ui/`, `responsive/`,
+`usability/`, and `accessibility/`.
+
+## Completion Standard
+
+A design architecture task is complete only when:
+
+- The user problem and success criteria are explicit.
+- The proposed experience has clear hierarchy, states, and flows.
+- Accessibility is considered from the design stage.
+- The design can be implemented with the project's platform constraints.
+- Reusable patterns and components are identified.
+- Trade-offs, open questions, and validation needs are documented.
+- Handoff notes are specific enough for design, product, and engineering partners.
+
+## Related Repository Areas
+
+- `skills/design-architecture/` for core design architecture competency.
+- `roles/software-developer/frontend/` for frontend implementation constraints.
+- `context/communication.md` for stakeholder communication norms.
+- `STYLE_GUIDE.md` for repository writing style.

package/roles/design-architect/accessibility/README.md

@@ -0,0 +1,33 @@
+# Accessibility Design
+
+Accessibility design ensures product experiences are perceivable, operable,
+understandable, and robust before implementation begins.
+
+## Scope
+
+- WCAG-oriented design requirements.
+- Contrast, typography, focus, keyboard, and screen reader behavior.
+- Inclusive interaction patterns for forms, dialogs, navigation, media, and data.
+- Reduced motion, zoom, text scaling, and multiple input methods.
+
+## Standards
+
+- Target WCAG AA unless the project defines a stricter standard.
+- Do not rely on color alone for meaning.
+- Design visible focus states for every interactive element.
+- Specify labels, descriptions, error messages, and announcements.
+- Include keyboard and assistive technology behavior in component specs.
+
+## Deliverables
+
+- Accessibility review notes.
+- WCAG mapping for high-risk issues.
+- Component accessibility requirements.
+- Keyboard and focus behavior notes.
+- Verification plan for automated and manual checks.
+
+## Related Guidance
+
+- `../component-library/` for component-level behavior.
+- `../ui/` for contrast, hierarchy, typography, and motion.
+- `../responsive/` for zoom, text scaling, and device variation.

package/roles/design-architect/accessibility/checklists.md

@@ -0,0 +1,29 @@
+# Accessibility Checklists
+
+## Design Checklist
+
+- [ ] Text contrast meets WCAG AA or project standard.
+- [ ] Color is never the only signal for status or validation.
+- [ ] Interactive elements have visible focus states.
+- [ ] Touch targets and click targets are appropriately sized.
+- [ ] Headings and labels communicate structure.
+- [ ] Form errors include explanation and recovery.
+- [ ] Dialogs define focus entry, focus trap, and close behavior.
+- [ ] Motion is optional or respects reduced-motion preferences.
+- [ ] Content remains usable at 200% zoom and with larger text.
+
+## Component Checklist
+
+- [ ] Component has an accessible name.
+- [ ] Required ARIA is specified only when native semantics are insufficient.
+- [ ] Keyboard behavior is documented.
+- [ ] Disabled and loading states communicate availability.
+- [ ] Error and success states are not color-only.
+- [ ] Screen reader announcements are defined for dynamic changes.
+
+## Review Checklist
+
+- [ ] Findings include severity and user impact.
+- [ ] Fixes are specific enough for implementation.
+- [ ] Automated checks are paired with manual keyboard and screen reader checks.
+- [ ] Any unresolved accessibility risk is documented.

package/roles/design-architect/accessibility/examples.md

@@ -0,0 +1,35 @@
+# Accessibility Examples
+
+## Form Error Pattern
+
+```text
+Input: Email address
+Error text: Enter an email address in the format name@example.com.
+Behavior:
+- Error appears below the field.
+- Field references the error with accessible description.
+- Summary at top links to the field after failed submit.
+- Focus moves to the summary only after submit, not while typing.
+```
+
+## Dialog Focus Pattern
+
+```text
+On open:
+- Focus moves to dialog title or first meaningful control.
+- Background content is inert.
+
+Inside dialog:
+- Tab cycles through interactive elements.
+- Escape closes unless the action is destructive and needs explicit choice.
+
+On close:
+- Focus returns to the element that opened the dialog.
+```
+
+## Status Pattern
+
+Use text and visual treatment together:
+
+- Good: `Failed` with error color and error icon.
+- Avoid: red dot with no text label.

package/roles/design-architect/checklists.md

@@ -0,0 +1,76 @@
+# Design Architect Checklists
+
+## Intake Checklist
+
+- [ ] User audience and primary job are identified.
+- [ ] Product goal and success metric are stated.
+- [ ] Deliverable and fidelity are clear.
+- [ ] Platform, device, brand, timeline, and technical constraints are known.
+- [ ] Existing components, tokens, patterns, and content are considered.
+- [ ] Assumptions and open questions are documented.
+
+## UX and Flow Checklist
+
+- [ ] Primary path is clear and short.
+- [ ] Secondary paths do not compete with the main task.
+- [ ] Entry points and exits are defined.
+- [ ] Empty, loading, error, success, disabled, and permission states are included.
+- [ ] Forms prevent avoidable errors and explain recovery.
+- [ ] Navigation labels match user language.
+- [ ] Destructive or irreversible actions have appropriate confirmation.
+
+## UI Quality Checklist
+
+- [ ] Visual hierarchy makes the next action obvious.
+- [ ] Typography is readable and consistently scaled.
+- [ ] Spacing and alignment follow a repeatable system.
+- [ ] Color supports meaning without being the only signal.
+- [ ] Actions are visually differentiated by importance.
+- [ ] Icons are recognizable or labeled.
+- [ ] Motion has a functional purpose and respects reduced-motion needs.
+
+## Accessibility Checklist
+
+- [ ] Text contrast meets WCAG AA or the project standard.
+- [ ] Focus order and keyboard behavior are defined.
+- [ ] Controls have accessible names and visible labels where needed.
+- [ ] Error messages are specific and associated with the related fields.
+- [ ] Non-text content has alt text or is marked decorative.
+- [ ] Layout works at 200% zoom and with text scaling.
+- [ ] Color, shape, text, or iconography provide redundant meaning for status.
+
+## Responsive Checklist
+
+- [ ] Small, medium, large, and high-density layouts are considered.
+- [ ] Breakpoints are based on content behavior.
+- [ ] Touch targets are large enough on touch devices.
+- [ ] Navigation adapts without hiding critical actions.
+- [ ] Tables, charts, and dense controls have mobile strategies.
+- [ ] Content does not overlap or truncate critical information.
+
+## Design System Checklist
+
+- [ ] Tokens cover color, type, spacing, radius, elevation, and motion.
+- [ ] Components include anatomy, variants, states, and usage guidance.
+- [ ] Accessibility behavior is documented per component.
+- [ ] Naming is consistent across design and code.
+- [ ] Exceptions and contribution rules are defined.
+- [ ] Adoption and migration path are practical for teams.
+
+## Handoff Checklist
+
+- [ ] Component mapping is documented.
+- [ ] Layout, spacing, sizing, and responsive rules are specified.
+- [ ] Interaction states and transitions are included.
+- [ ] Copy, validation, and error behavior are clear.
+- [ ] Accessibility requirements are explicit.
+- [ ] Analytics or success measurement needs are noted.
+- [ ] Risks, assumptions, and open questions are visible.
+
+## Review Checklist
+
+- [ ] Findings are prioritized by user and system impact.
+- [ ] Each critique explains the issue, why it matters, and a specific fix.
+- [ ] Feedback avoids vague taste language.
+- [ ] Recommendations fit current constraints.
+- [ ] Required validation or engineering checks are named.

package/roles/design-architect/component-library/README.md

@@ -0,0 +1,35 @@
+# Component Library
+
+A component library defines reusable interface building blocks, their variants,
+states, behavior, accessibility requirements, and usage rules.
+
+## Scope
+
+- Component inventory and naming.
+- Anatomy, slots, variants, and states.
+- Composition rules and responsive behavior.
+- Accessibility and interaction specifications.
+- Adoption, contribution, and deprecation guidance.
+
+## Standards
+
+- Components should solve repeated product needs.
+- Each component needs a clear purpose and usage boundary.
+- Variants should be meaningful, not cosmetic drift.
+- States must include default, hover, focus, active, disabled, loading, error,
+  success, empty, and selected when relevant.
+- Design and code names should align whenever possible.
+
+## Deliverables
+
+- Component inventory.
+- Component specs.
+- Variant and state matrix.
+- Usage guidance and anti-patterns.
+- Migration or contribution notes.
+
+## Related Guidance
+
+- `../design-system/` for tokens and foundations.
+- `../accessibility/` for inclusive behavior.
+- `../figma/` for component sets and handoff.

package/roles/design-architect/component-library/checklists.md

@@ -0,0 +1,29 @@
+# Component Library Checklists
+
+## Component Definition Checklist
+
+- [ ] Purpose is clear.
+- [ ] Anatomy and slots are named.
+- [ ] Props or configuration options are documented conceptually.
+- [ ] Variants are limited and meaningful.
+- [ ] Required states are specified.
+- [ ] Content rules and truncation behavior are defined.
+- [ ] Accessibility behavior is documented.
+- [ ] Responsive behavior is documented.
+- [ ] Usage examples and anti-patterns are included.
+
+## Library Governance Checklist
+
+- [ ] Component owner or review path is identified.
+- [ ] Contribution criteria are defined.
+- [ ] Deprecation and migration process exists.
+- [ ] Design and code naming are aligned.
+- [ ] New components are justified by repeated need.
+- [ ] Documentation is easy to find and update.
+
+## Review Checklist
+
+- [ ] Component does not duplicate an existing pattern.
+- [ ] Variants do not encode one-off product requests.
+- [ ] States are complete enough for implementation.
+- [ ] Accessibility requirements are testable.

package/roles/design-architect/component-library/examples.md

@@ -0,0 +1,35 @@
+# Component Library Examples
+
+## Component Spec Template
+
+```text
+Component:
+Purpose:
+Anatomy:
+Variants:
+States:
+Content rules:
+Interactions:
+Responsive behavior:
+Accessibility:
+Do:
+Do not:
+Related components:
+```
+
+## Example: Empty State
+
+```text
+Component: EmptyState
+Purpose: Explain why content is absent and guide the next useful action.
+Variants: No data, no results, permission blocked, first use.
+Anatomy: Illustration or icon, title, body, primary action, optional secondary action.
+States: Default, loading replacement, compact.
+Accessibility: Icon is decorative unless it conveys meaning. Title is announced as part of page structure.
+Do not: Use as a generic error state.
+```
+
+## Variant Rule
+
+Add a new variant when the component needs a distinct behavior or semantic role.
+Do not add a variant only to preserve a one-off visual tweak.

package/roles/design-architect/design-system/README.md

@@ -0,0 +1,35 @@
+# Design System
+
+A design system is the shared product language for foundations, components,
+patterns, documentation, and governance.
+
+## Scope
+
+- Foundations: color, type, spacing, radius, elevation, iconography, motion.
+- Tokens and theming.
+- Component and pattern standards.
+- Documentation and contribution workflows.
+- Adoption, migration, and governance.
+
+## Standards
+
+- Tokens should describe intent, not only raw values.
+- Components should map to real product use cases.
+- Documentation should explain when to use a pattern and when not to.
+- Accessibility must be built into foundations and components.
+- Governance should make reuse easier than reinvention.
+
+## Deliverables
+
+- System audit.
+- Token model.
+- Component inventory.
+- Pattern library outline.
+- Governance model.
+- Adoption and migration plan.
+
+## Related Guidance
+
+- `../component-library/` for component specs.
+- `../figma/` for design asset structure.
+- `../accessibility/` for inclusive foundations.