ac-framework 1.9.2 → 1.9.3

package/framework/web_development/.factory/skills/requirement-checklist/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: requirement-checklist
+description: Generate comprehensive checklists to validate requirements quality (Unit Tests for Specs). Critically examine the spec for clarity, completeness, and consistency before implementation starts.
+---
+
+# Requirement Checklist Generation
+
+## Overview
+
+Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing implementation**:
+*   ❌ NOT "Verify the button clicks correctly"
+*   ❌ NOT "Test error handling works"
+*   ❌ NOT "Confirm the API returns 200"
+*   ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+*   ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+*   ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+*   ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+*   ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+*   ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+## Execution Steps
+
+1.  **Setup**:
+    *   Parse feature directory and available docs list.
+    *   Identify the target feature spec (`spec.md`, `plan.md`, `tasks.md`).
+
+2.  **Clarify intent (dynamic)**:
+    *   Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+        *   Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+        *   Only ask about information that materially changes checklist content
+    *   Generation algorithm:
+        1.  Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+        2.  Cluster signals into candidate focus areas (max 4) ranked by relevance.
+        3.  Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+        4.  Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+
+3.  **Generate checklist - Create "Unit Tests for Requirements"**:
+    *   Create a checklist file in the feature directory (e.g., `checklists/[domain].md`).
+    *   Format: `[domain].md` (e.g., `ux.md`, `api.md`, `security.md`).
+    *   Number items sequentially starting from CHK001.
+    *   Each run creates a NEW file (never overwrites existing checklists unless explicitly told).
+
+    **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+    Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+    *   **Completeness**: Are all necessary requirements present?
+    *   **Clarity**: Are requirements unambiguous and specific?
+    *   **Consistency**: Do requirements align with each other?
+    *   **Measurability**: Can requirements be objectively verified?
+    *   **Coverage**: Are all scenarios/edge cases addressed?
+
+    **Category Structure**:
+    *   Requirement Completeness
+    *   Requirement Clarity
+    *   Requirement Consistency
+    *   Acceptance Criteria Quality
+    *   Scenario Coverage
+    *   Edge Case Coverage
+    *   Non-Functional Requirements
+    *   Dependencies & Assumptions
+    *   Ambiguities & Conflicts
+
+4.  **Structure Reference**:
+    *   Generate the checklist following a markdown template: Title, Purpose, Category Headings, `##` sections, `- [ ] CHK### <requirement item>` lines.
+
+5.  **Report**:
+    *   Output full path to created checklist, item count, and remind user that each run creates a new file.
+    *   Summarize focus areas selected, depth level, and valid user must-haves.
+
+## Checklist Item Guidelines
+
+**Example Checklist Items**:
+
+*   **UX**: "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+*   **API**: "Are error response formats specified for all failure scenarios? [Completeness]"
+*   **Performance**: "Are performance requirements quantified with specific metrics? [Clarity]"
+*   **Security**: "Are authentication requirements specified for all protected resources? [Coverage]"
+
+**Avoid Implementation Tests**:
+*   ❌ "Verify landing page displays 3 episode cards"
+*   ❌ "Test hover states work correctly on desktop"
+*   ❌ "Confirm logo click navigates to home page"
+
+**Use Quality Checks**:
+*   ✅ "Are the exact number and layout of featured episodes specified?" [Completeness]
+*   ✅ "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+*   ✅ "Are hover state requirements consistent across all interactive elements?" [Consistency]

package/framework/web_development/.factory/skills/research-retrieval/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: research-retrieval
+description: Search external documentation (web pages, API docs, papers) and generate useful summaries for development. Use when investigating new technologies, understanding third-party APIs, researching best practices, or gathering information for technical decisions. Reduces hallucinations and expands agent knowledge.
+license: MIT
+metadata:
+  author: AC Framework
+  version: "1.0"
+---
+
+# Research & Retrieval
+
+External knowledge search, documentation retrieval, and synthesis for informed development decisions.
+
+## When to Use This Skill
+
+Use this skill when:
+- Investigating new technologies, libraries, or frameworks
+- Understanding third-party APIs and their capabilities
+- Researching best practices for a specific problem
+- Gathering information for architecture decisions
+- Need to verify facts or current information
+- Exploring solutions to unfamiliar problems
+
+## Instructions
+
+### Step 1: Define Research Goals
+
+1. **Clarify what you need to know**:
+   - Specific technical question
+   - Comparison of technologies
+   - Implementation approach
+   - Best practices
+
+2. **Identify sources**:
+   - Official documentation
+   - API references
+   - Technical blogs
+   - Research papers
+   - GitHub repositories
+   - Stack Overflow
+
+3. **Set scope boundaries**:
+   - Time period (recent vs. historical)
+   - Version specificity
+   - Language/framework constraints
+
+### Step 2: Search and Retrieve
+
+**Official Documentation**:
+```
+Priority sources:
+1. Official docs (docs.{service}.com)
+2. API reference
+3. Getting started guides
+4. Best practices
+5. Changelog/release notes
+```
+
+**Technical Blogs & Articles**:
+```
+Quality indicators:
+- Recent publication date
+- Author expertise/credentials
+- Code examples included
+- Community engagement
+- Updated for current versions
+```
+
+**Research Papers** (for advanced topics):
+```
+Use when:
+- Novel algorithms needed
+- Performance optimizations
+- Academic foundations
+- Cutting-edge techniques
+```
+
+**GitHub Repositories**:
+```
+Evaluate by:
+- Stars/forks (popularity)
+- Recent commits (maintenance)
+- Issue resolution (support)
+- Documentation quality
+- Test coverage
+```
+
+### Step 3: Evaluate Sources
+
+**Credibility Checklist**:
+- [ ] Authoritative source (official > third-party)
+- [ ] Up-to-date information
+- [ ] Well-explained with examples
+- [ ] Community-validated (comments, issues)
+- [ ] Version compatibility noted
+
+**Red Flags**:
+- Outdated documentation
+- Unexplained "magic" solutions
+- No code examples
+- Deprecated approaches
+- Unsupported claims
+
+### Step 4: Extract Key Information
+
+For each relevant source, extract:
+
+```markdown
+## Source: [Title/URL]
+
+**Relevance**: [High/Medium/Low]
+**Date**: [Publication date]
+**Version**: [Software version, if applicable]
+
+### Key Points
+
+1. [Important finding 1]
+2. [Important finding 2]
+3. [Important finding 3]
+
+### Code Examples
+
+\`\`\`[language]
+// Relevant code snippet
+\`\`\`
+
+### Warnings/Caveats
+
+- [Known issues or limitations]
+- [Breaking changes]
+- [Performance considerations]
+
+### References
+
+- [Link 1]
+- [Link 2]
+```
+
+### Step 5: Synthesize Findings
+
+**Compare approaches**:
+
+```markdown
+## Technology Comparison: [Topic]
+
+### Option A: [Technology A]
+
+**Pros**:
+- Advantage 1
+- Advantage 2
+
+**Cons**:
+- Disadvantage 1
+- Disadvantage 2
+
+**Best for**: [Use cases]
+
+### Option B: [Technology B]
+
+**Pros**:
+- Advantage 1
+- Advantage 2
+
+**Cons**:
+- Disadvantage 1
+- Disadvantage 2
+
+**Best for**: [Use cases]
+
+### Recommendation
+
+[Your recommendation with justification]
+```
+
+**Synthesize best practices**:
+
+```markdown
+## Best Practices: [Topic]
+
+Based on [N] sources, consensus on:
+
+### Do's
+1. [Recommended approach 1]
+2. [Recommended approach 2]
+
+### Don'ts
+1. [Anti-pattern 1]
+2. [Anti-pattern 2]
+
+### Trade-offs
+- [Decision point]: [Option A] vs [Option B]
+  - Choose A when: [conditions]
+  - Choose B when: [conditions]
+```
+
+### Step 6: Generate Actionable Steps
+
+Convert research into implementation steps:
+
+```markdown
+## Implementation Guide: [Topic]
+
+### Prerequisites
+- [Requirement 1]
+- [Requirement 2]
+
+### Step-by-Step
+
+1. **Setup**
+   - [Action 1]
+   - [Action 2]
+
+2. **Configuration**
+   - [Action 3]
+   - [Action 4]
+
+3. **Implementation**
+   - [Action 5]
+   - [Action 6]
+
+4. **Testing**
+   - [Action 7]
+
+### Common Pitfalls
+- [Pitfall 1] → [Solution]
+- [Pitfall 2] → [Solution]
+```
+
+### Step 7: Store for Reuse
+
+Save findings in `references/` directory:
+
+```
+references/
+├── README.md (index of all references)
+├── api/
+│   ├── stripe-api-2024-01.md
+│   └── openai-api-best-practices.md
+├── libraries/
+│   ├── react-server-components.md
+│   └── state-management-comparison.md
+└── patterns/
+    ├── authentication-patterns.md
+    └── caching-strategies.md
+```
+
+### Step 8: Link to OpenSpec
+
+Reference research in specs:
+
+```markdown
+## Specification: [Feature]
+
+### Research References
+
+- [Authentication Patterns](../references/patterns/authentication-patterns.md)
+- [Stripe API Integration](../references/api/stripe-api-2024-01.md)
+
+### Decisions Based on Research
+
+1. **Use JWT for authentication**
+   - Rationale: [Summary of research findings]
+   - Sources: [Links to references]
+
+2. **Implement Redis caching**
+   - Rationale: [Performance benchmarks from research]
+   - Sources: [Links to references]
+```
+
+## Output Format
+
+After research is complete:
+
+```
+## Research Summary: [Topic]
+
+**Sources Consulted**: [N]
+**Date**: [Research date]
+**Confidence**: [High/Medium/Low]
+
+### Executive Summary
+
+[2-3 sentence overview of findings]
+
+### Key Findings
+
+1. [Finding 1 with source]
+2. [Finding 2 with source]
+3. [Finding 3 with source]
+
+### Recommendations
+
+1. [Actionable recommendation 1]
+2. [Actionable recommendation 2]
+
+### Implementation Steps
+
+[Step-by-step guide based on research]
+
+### References Stored
+
+- references/[category]/[filename].md
+- [Link to full research document]
+
+### Uncertainties/Gaps
+
+- [What still needs investigation]
+- [Questions that remain unanswered]
+```
+
+## Guardrails
+
+- **Verify critical information** - Cross-reference multiple sources
+- **Check publication dates** - Avoid outdated information
+- **Prefer official docs** - Authoritative over anecdotal
+- **Acknowledge uncertainty** - Be clear when information is incomplete
+- **Document sources** - Always cite where information came from
+- **Focus on actionable info** - Avoid research rabbit holes
+
+## Search Strategies
+
+**Error Messages**:
+```
+"[exact error message]" + [technology name]
+```
+
+**Feature Comparisons**:
+```
+[technology A] vs [technology B] 2024
+[technology A] alternative
+```
+
+**Best Practices**:
+```
+[technology] best practices
+[technology] common pitfalls
+```
+
+**Implementation Guides**:
+```
+[technology] getting started tutorial
+[technology] example project
+```
+
+## Requirements
+
+- Web search capability
+- Access to documentation sites
+- Ability to evaluate source credibility
+- Understanding of the domain being researched
+
+## See Also
+
+- `context-synthesizer` - Integrate research into project context
+- `spec-clarification` - Use research to clarify requirements
+- `documentation` - Document findings
+- `brainstorming` - Generate ideas based on research