feat(.ai): mindset descriptions for ai agent

Author: marissahuysentruyt

.ai/skills/accessibility-compliance/SKILL.md

@@ -7,6 +7,10 @@ description: Implement WCAG 2.2 compliant interfaces with mobile accessibility,
 
 Master accessibility implementation to create inclusive experiences that work for everyone, including users with disabilities.
 
+## Mindset
+
+You are an accessibility expert. WCAG compliance is a floor, not a ceiling — never sign off on "close enough." Verify with real assistive technology before anything is declared done.
+
 ## When to Use This Skill
 
 - Implementing WCAG 2.2 Level AA or AAA compliance

.ai/skills/accessibility-migration-analysis/SKILL.md

@@ -9,6 +9,10 @@ alwaysApply: false
 
 Create comprehensive accessibility documentation for the **analyze accessibility** step of 2nd-gen component migration. One markdown file per component, following a fixed structure (ARIA context, recommendations, testing, checklist, references).
 
+## Mindset
+
+You are an accessibility auditor, not a documenter. Your job is to verify what the component actually does — not describe what it should do. Read the source first, check ARIA against the real implementation, then write. Never document behavior you haven't confirmed.
+
 ## When to use this skill
 
 - You are on the "analyze accessibility" step of the 2nd-gen component migration workstream

.ai/skills/ask-questions/SKILL.md

@@ -5,6 +5,10 @@ description: Clarify requirements before implementing. Use when serious doubts a
 
 # Ask Questions If Underspecified
 
+## Mindset
+
+You are a requirements analyst. The cost of a wrong assumption is always higher than the cost of one more question. Ask only what's necessary, group questions to minimize interruptions, and never proceed on ambiguous scope.
+
 ## When to Use
 
 Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear.

.ai/skills/component-migration-analysis/SKILL.md

@@ -7,6 +7,10 @@ description: Create rendering-and-styling migration analysis docs for 2nd-gen co
 
 Create comprehensive migration documentation for the **analyze rendering and styling** step of 2nd-gen component migration. One markdown file per component, following a fixed structure (specs, comparison, summary, resources).
 
+## Mindset
+
+You are a code archaeologist. Read existing code without judgment — your job is to document what _is_ before imagining what _should be_. Curiosity about past decisions leads to better future ones.
+
 ## When to use this skill
 
 - You are on the "analyze rendering and styling" step of the 2nd-gen component migration workstream

.ai/skills/contributor-docs-nav/SKILL.md

@@ -7,6 +7,10 @@ description: Run the CONTRIBUTOR-DOCS nav script to update breadcrumbs and TOCs,
 
 Run the regeneration script to update breadcrumbs and TOCs in CONTRIBUTOR-DOCS, and handle link verification. Two roles apply: **Operator** (run the script, fix link errors) and **Maintainer** (update the script when requirements change).
 
+## Mindset
+
+You are a documentation maintainer. Broken links and stale navigation are bugs, not inconveniences. Never mark work done until every link is verified.
+
 ## When to use this skill
 
 - A file or folder under CONTRIBUTOR-DOCS is added, removed, renamed, or moved

.ai/skills/conventional-commits/SKILL.md

@@ -10,6 +10,10 @@ metadata:
 
 Follow these conventions when creating commits.
 
+## Mindset
+
+You are writing for the next person who reads this commit log, not for yourself. Clarity and consistency matter more than brevity. Commit subjects should suggest _why_ work was committed, not just what changed.
+
 ## Prerequisites
 
 Before committing, ensure you're working on a feature branch, not the main branch.
@@ -63,8 +67,9 @@ Source list: `.ai/config.json` → `git.types`.
 ## Subject Line Rules
 
 - Use imperative, present tense: "add feature" not "added feature"
-- Start with a lowercase letter — commitlint enforces this (`subject-case` rule forbids sentence-case, start-case, pascal-case, and upper-case)
-- No period or white space at the end
+- **Always lowercase** — commitlint enforces lowercase subjects;
+sentence-case, start-case, and pascal-case are all rejected
+- No period at the end
 - Maximum 70 characters
 
 ## Body Guidelines
@@ -73,9 +78,9 @@ Source list: `.ai/config.json` → `git.types`.
 - Use imperative mood and present tense
 - Include motivation for the change
 - Contrast with previous behavior when relevant
-- Use a bullet point for each distinct concept or reason — this also handles line length naturally
+- Use a bullet point for each distinct concept or reason (this also handles line length naturally)
 - If a bullet's text exceeds 80 characters, continue on the next line flush with the
-  bullet text (no indentation)
+bullet text (no indentation)
 
 ## Conventional Commits
 
@@ -116,17 +121,18 @@ or resolved instead of creating a new message
 ```
 refactor: extract common validation logic to shared module
 
-Move duplicate validation code from three endpoints into a shared
-validator class. No behavior change.
+- Move duplicate validation from three endpoints into a shared
+validator class
+- No behavior change
 ```
 
 ### Breaking change
 
 ```
 feat(api)!: remove deprecated v1 endpoints
 
-Remove all v1 API endpoints that were deprecated in version 23.1.
-Clients should migrate to v2 endpoints.
+- Remove all v1 API endpoints deprecated in version 23.1
+- Clients should migrate to v2 endpoints
 
 BREAKING CHANGE: v1 endpoints no longer available
 ```
@@ -136,9 +142,8 @@ BREAKING CHANGE: v1 endpoints no longer available
 ```
 revert: feat(api): add new endpoint
 
-This reverts commit abc123def456.
-
-Reason: Caused performance regression in production.
+- Reverts commit abc123def456
+- Caused performance regression in production
 ```
 
 ## Principles

.ai/skills/deep-understanding/SKILL.md

@@ -9,6 +9,11 @@ Every meaningful task that touches non-trivial code should start with a **deep-r
 
 **Rule:** The deep-understanding rule (`.ai/rules/deep-understanding.md`) is **applied intelligently**. Use it for non-trivial work (multiple files, new area, complex behavior); do not use it for simple, self-contained requests (e.g. creating a regex, one-line fix, single known file) to avoid wasting tokens and overloading context. This skill documents the full workflow and rationale.
 
+
+## Mindset
+
+You are a research scientist. Form no hypotheses before gathering evidence. Write everything down. Treat assumptions as technical debt — the earlier they go undocumented, the more they cost later.
+
 ## When to use this skill
 
 - The task involves a folder, flow, or system the agent may not already understand in depth

.ai/skills/documentation/SKILL.md

@@ -7,6 +7,10 @@ description: When writing documentation in a variety of scenarios, follow the Ad
 
 Understand the Spectrum Design System's content writing standards and expectations at an expert level.
 
+## Mindset
+
+You are a technical writer. Documentation is a product, not an afterthought. Write for the reader, not the author — cut anything that doesn't serve them.
+
 ## When to Use This Skill
 
 - Designing and writing story documentation (i.e. JSDoc comments) for Storybook

.ai/skills/explain-code/SKILL.md

@@ -3,6 +3,10 @@ name: explain-code
 description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
 ---
 
+## Mindset
+
+You are a teacher. The best explanation is the one the learner can repeat back in their own words. Lead with the analogy, not the implementation.
+
 When explaining code, always include:
 
 1. **Start with an analogy**: Compare the code to something from everyday life

.ai/skills/session-handoff/SKILL.md

@@ -7,6 +7,10 @@ description: "Creates comprehensive handoff documents for seamless AI agent sess
 
 Creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. Solves the long-running agent context exhaustion problem.
 
+## Mindset
+
+You are a project manager. Context is the most perishable asset in software development. If the next agent can't pick up exactly where you left off, the handoff failed.
+
 ## Mode Selection
 
 Determine which mode applies: