
dev-skills
Lightweight skills for users with existing workflows - coding best practices, testing principles, and design guidelines without recipe workflows or agents
- version
- 0.31.0
- GitHub stars
- 718
Install
/plugin install dev-skills@claude-code-workflowsRun it inside Claude Code after adding the marketplace with /plugin marketplace add shinpr/claude-code-workflows.
Contents
Discovered from sourceSkills 9
AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection
Value-First Engineering
Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable.
- Resolve verified problems within scope or dependencies required for the outcome; report other findings with their owning boundary and evidence without expanding the active change.
- Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling when a current outcome, verified constraint, or evidence-backed material risk requires them.
- Treat behavior-preserving maintenance inside the assigned responsibility as current maintainer value when repository evidence shows it reduces change ambiguity, duplicate ownership, defect risk, or future implementation and verification cost without expanding observable product scope.
Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity.
Technical Anti-patterns (Red Flag Patterns)
Pause the affected decision and review the design when detecting the following patterns:
Code Quality Anti-patterns
- Duplicating one responsibility across independently maintained locations - Review whether the duplicated logic has one change reason and should have one owner
- Multiple responsibilities mixed in a single file - Violates Single Responsibility Principle (SRP)
- Defining same content in multiple files - Violates DRY principle
- Making changes without checking dependencies - Potential for unexpected impacts
- Disabling code with comments - Should use version control
- Error suppression - Hiding problems creates technical debt
- Bypassing safety mechanisms (type systems, validation, contracts) - Circumventing language's correctness guarantees
Design Anti-patterns
- "Make it work for now" thinking - Accumulation of technical debt
- Patchwork implementation - Unplanned additions to existing code
- Symptomatic fixes - Surface-level fixes that don't solve root causes
- Unplanned large-scale changes - Lack of incremental approach
Fail-Fast Fallback Design Principles
Core Principle
Make all errors visible and traceable with full context. Prioritize primary code reliability over fallback implementations. Excessive fallback mechanisms mask errors and make debugging difficult.
Implementation Guidelines
Default Approach
- Give every failure an explicit outcome: propagate it, translate it to the boundary's error contract, or recover through an accepted fallback
- Make failures explicit: Errors should be visible and traceable
- Preserve error context: Include original error information when re-throwing
When Fallbacks Are Acceptable
- Accepted recovery contract: A requirement, Design Doc, existing boundary contract, or project policy defines why degraded behavior is preferable to failure
- Business-critical continuity: When partial functionality is better than none
- Graceful degradation paths: Clearly defined degraded service levels
Layer Responsibilities
-
Infrastructure Layer:
- Preserve the original cause and operational context
- Propagate, translate, or return the failure in the form required by the caller's boundary contract
- Perform infrastructure-owned cleanup or retry only when that boundary owns it; business recovery decisions remain in the application layer
-
Application Layer:
- Make business-driven error handling decisions
- Implement fallbacks only when an accepted recovery contract defines the degraded outcome
- Make fallback activation observable through the project's established logging, metrics, or user-visible state when diagnosis or recovery requires it
Error Masking Detection
Review Triggers (require design review):
- Adding an error handler that duplicates or fragments an existing recovery responsibility
- The same failure is caught at multiple layers without a single recovery owner
- Nested handlers obscure which state is committed, rolled back, or exposed
- A handler converts a failure to success/default output without an observable degraded-state contract
- Recovery behavior that hides a failure from the boundary responsible for diagnosis or recovery
Another handler may remain when it covers a distinct failure mode with a documented recovery owner, state outcome, and observable signal.
Before Implementing Any Fallback:
- Identify the accepted requirement, boundary contract, project policy, or Design Doc entry that defines this fallback
- Document the business justification
- Make activation observable at the boundary that owns diagnosis or recovery through one existing UI, log, or metric channel; when logging is that channel, log once with sensitive data redacted
- Add new monitoring or alerting only when an operational requirement or project policy requires it
Implementation Pattern
AVOID: Silent fallback that hides errors
<handle error>:
return DEFAULT_VALUE // Error hidden, debugging impossible
PREFERRED: Explicit failure with context
<handle error>:
<attach operation context>
IF this boundary owns diagnosis: <log once>
<propagate error> // Re-throw exception, return Error, return error tuple
Adaptation: Use language-appropriate error handling (exceptions, Result types, error tuples, etc.)
Criteria for Code Duplication
Keep concrete implementations separate while their apparent similarity is accidental or their change reasons differ. Consolidate when repository evidence shows the same business rule, algorithm, validation contract, or coordinated change responsibility is maintained in multiple places.
Criteria for Commonalization
Cases for Commonalization
- Business logic duplication
- Complex processing algorithms
- Areas likely requiring bulk changes
- Validation rules
Cases to Avoid Commonalization
- Accidental matches (coincidentally same code)
- Contracts or change reasons that evidence shows differ
- Significant readability decrease from commonalization
- Simple helpers in test code
Common Failure Patterns and Avoidance Methods
Pattern 1: Error Fix Chain
Symptom: Fixing one error causes new errors Cause: Surface-level fixes without understanding root cause Avoidance: Identify root cause with 5 Whys before fixing
Pattern 2: Circumventing Correctness Guarantees
Symptom: Bypassing safety mechanisms (type systems, validation, contracts) Cause: Impulse to avoid correctness errors Avoidance: Use language-appropriate safety mechanisms (static checking, runtime validation, contracts, assertions)
Pattern 3: Implementation Without Sufficient Testing
Symptom: Many bugs after implementation Cause: Accepted behavior left without a test that proves it Avoidance: Prove each delivered behavior at the boundary where it is observed
Pattern 4: Building on Unverified Premises
Symptom: Dependent work fails, or workarounds accumulate, once an assumed premise proves false Cause: Treating an assumed capability, behavior, or existing implementation as fact Avoidance: When an unverified premise could invalidate the chosen approach, check it by the cheapest sufficient means before building dependent work on it. When results contradict the premise, reconsider the approach before patching its parts. Keep this reasoning in the active task; it needs no separate artifact.
Pattern 5: Insufficient Existing Code Investigation
Symptom: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns Cause: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness Avoidance Methods:
- Before implementation, find functionality that already holds the same responsibility and the code that depends on the change, as coding-principles Reference Representativeness describes; similar functionality may share no name with the new code
- Similar functionality found → Verify that its contract, lifecycle, and repository usage are representative; reuse or extend it when compatible, otherwise record why it is not a valid model
- Similar functionality is technical debt → Repair it when it blocks the current outcome, was caused by the current change, or lies in scope; otherwise report it separately. Create an ADR when the repair requires an architectural decision
- No similar functionality exists → Implement new functionality following existing design philosophy
- Preserve the evidence for each reuse, extend, separate, or repair decision in the applicable implementation or design record
Quality Assurance Mechanism Awareness
Before executing quality checks, identify what quality mechanisms exist for the change area:
- Primary detection: inspect the change area's file types, project manifest, and configuration to identify applicable quality tools
- Check CI pipeline definitions for checks that cover the affected paths
- Check for domain-specific linter or validator configurations (e.g., schema validators, API spec validators, configuration file linters)
- Check for domain-specific constraints in project configuration (naming rules, length limits, format requirements)
- Run verification methods supplied by the governing work artifact as change-specific checks
- Include discovered domain-specific checks alongside standard quality phases below
Quality Check Workflow
Discover the repository's configured quality entry points and the categories they cover. Use the categories below as the applicable evidence checklist:
- Static checks: formatting, linting, unused-code detection, type checking, and configured static analysis
- Build checks: compilation or production build, dependency resolution, and configured resource validation
- Behavior checks: the smallest configured tests that exercise the changed behavior, plus integration or E2E suites when the change crosses their boundary, a generated skeleton requires them, or the repository gate includes them
Follow repository-declared command composition or ordering when it exists. Otherwise choose an order that respects command dependencies and provides useful feedback. Completion requires every applicable configured check to pass.
Situations Requiring Technical Decisions
Timing of Abstraction
- Extract a shared abstraction after repository evidence shows a responsibility with the same contract and change reason maintained in more than one place
- Be conscious of YAGNI, implement only currently needed features
- Prioritize current simplicity over future extensibility
Performance vs Readability
- Prioritize readability unless profiling identifies a measurable bottleneck (e.g., response time exceeding SLA, memory exceeding allocation)
- Measure before optimizing
- Document reason with comments when optimizing
Granularity of Contracts and Interfaces
- Overly detailed contracts reduce maintainability
- Design interfaces where each method maps to a single domain operation and parameter types use domain vocabulary
- Use abstraction mechanisms to reduce duplication
Scope Expansion
- Apply implementation/edit instructions to the accepted outcome and its governing scope.
- Treat explicit restrictions and quantities ("one", "this file", "only X") in the governing request or the outcome, desired-future requirements, and non-goals as hard boundaries; treat technical-artifact How as a correctable baseline when repository evidence invalidates it without changing those boundaries
- Treat referenced or expected paths as investigation starting points unless the governing source explicitly makes them exclusive
- Copy/move/mirror requests preserve content verbatim; edit content only when requested
- Port/translation requests preserve intent and behavior; adapt only what the destination context requires
- Include related files, symmetric locations, and adjacent behavior when evidence shows they are required by the same accepted outcome or consistency contract; report unrelated improvements separately
Implementation Completeness Assurance
Impact Analysis: Risk-Scaled 3-Stage Process
Complete these stages sequentially before implementation. For an isolated change with no public contract, data-flow, integration, or configuration impact, concise notes or search evidence are sufficient. Use the structured report for cross-boundary, high-risk, or multi-consumer changes.
1. Discovery - Identify all affected code:
- Implementation references (imports, calls, instantiations)
- Interface dependencies (contracts, types, data structures)
- Behavior-relevant test evidence
- Configuration (build configs, env settings, feature flags)
- Documentation (comments, docs, diagrams)
2. Understanding - Analyze each discovered location:
- Role and purpose in the system
- Dependency direction (consumer or provider)
- Data flow (origin → transformations → destination)
- Coupling strength
3. Identification - Record the affected units, risks, and implementation order at the depth required by the change. For expanded analysis, use:
## Impact Analysis
### Direct Impact
- [Unit]: [Reason and modification needed]
### Indirect Impact
- [System]: [Integration path → reason]
### Data Flow
[Source] → [Transformation] → [Consumer]
### Risk Assessment
- High: [Complex dependencies, fragile areas]
- Medium: [Moderate coupling, test gaps]
- Low: [Isolated, well-tested areas]
### Implementation Order
1. [Start with lowest risk or deepest dependency]
2. [...]
Proceed when discovery and understanding cover the accepted outcome, governing boundaries, and required adjacent dependencies, and each material risk has an implementation, verification, or unresolved-decision disposition.
Unused Code Deletion
When an artifact made obsolete by the requested change is detected:
- Delete it in the same change when its callers and generated/operational uses are checked
- Preserve and report it when obsolescence is uncertain or deletion would expand beyond the accepted outcome and governing boundaries
- Keep unrelated dormant code outside the implementation scope
Existing Code Modification
Required by the requested change? No → Preserve unless the change proves it obsolete
Yes → Working and compatible? Yes → Fix/Extend
No → Repair or replace with migration/rollback evidence
Principle: Prefer clean implementation over patching broken code
References
- references/frontend.md: read when implementing, reviewing, fixing, or diagnosing frontend code
Language-Agnostic Coding Principles
Core Philosophy
- Maintainability over Speed: Prioritize long-term code health over initial development velocity
- Simplicity First: Choose the simplest solution that meets requirements (YAGNI principle)
- Design Convergence: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first.
- Explicit over Implicit: Make intentions clear through code structure and naming
- Delete over Comment: Remove unused code instead of commenting it out
Code Quality
Continuous Improvement
- Refactor related code inside the accepted outcome and governing boundaries when it reduces the change's risk or maintenance cost
- Improve code structure incrementally
- Keep the codebase lean and focused
- Delete code proven obsolete by the requested change after checking its callers; report uncertain or out-of-scope cleanup separately
Readability
- Use meaningful, descriptive names drawn from the problem domain
- Use full words in names; abbreviations are acceptable only when widely recognized in the domain
- Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)
- Extract magic numbers and strings into named constants
- Keep code self-documenting where possible
Function Design
Parameter Management
- Group related positional parameters into an object, struct, or dictionary when call-site clarity or coordinated evolution requires it. Retain positional parameters when their order is conventional and the call remains clear, or an external/public signature requires them
- Preserve external/public signatures unless their migration is part of the accepted outcome or governing artifact
Single Responsibility
- Each function should do one thing well
- Extract a function when independently changing responsibilities or obscured control flow make the current unit harder to understand, verify, or reuse; retain a cohesive domain flow when extraction would create artificial coupling
- Extract complex logic into separate, well-named functions
- Functions should have a single level of abstraction
Function Organization
- Pure functions when possible (no side effects)
- Separate data transformation from side effects
- Use early returns to reduce nesting
- Use early returns or extraction when nesting obscures state transitions or decision ownership; retain nested structure when it maps the domain decision more clearly
Error Handling
Error Management Principles
- Always handle errors: Log with context or propagate explicitly
- Log appropriately: Include context for debugging
- Protect sensitive data: Mask or exclude passwords, tokens, PII from logs
- Fail fast: Detect and report errors as early as possible
Error Propagation
- Use language-appropriate error handling mechanisms
- Propagate errors to appropriate handling levels
- Provide meaningful error messages
- Include error context when re-throwing
Dependency Management
Loose Coupling via Parameterized Dependencies
- Inject external dependencies as parameters (constructor injection for classes, function parameters for procedural/functional code)
- Depend on abstractions, not concrete implementations
- Minimize inter-module dependencies
- Facilitate testing through mockable dependencies
Reference Representativeness
Existing code relates to a change in two ways. Code that depends on it — callers, consumers, configuration — is reached through references to the changed code. Code that already holds the same responsibility may share no name or reference with it; reach it through position and role (sibling features, files with the same role in the same layer, shared layers) and through the input it takes and the purpose it serves, then compare their logic to judge whether the responsibility is the same.
When alternatives coexist, choose the pattern from responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice.
Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Stop when the candidates that could change implementation or proof have been read and judged; a search with no match shows only that the search found nothing. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable.
Performance Considerations
Optimization Approach
- Measure first: Profile before optimizing
- Focus on algorithms: Algorithmic complexity > micro-optimizations
- Use appropriate data structures: Choose based on access patterns
- Resource management: Handle memory, connections, and files properly
When to Optimize
- After identifying actual bottlenecks through profiling
- When performance issues are measurable
- Optimize only after measurable bottlenecks are identified, not during initial development
Code Organization
Structural Principles
- Group related functionality: Keep related code together
- Separate concerns: Domain logic, data access, presentation
- Consistent naming: Follow project conventions
- Module cohesion: High cohesion within modules, low coupling between
File Organization
- One primary responsibility per file
- Logical grouping of related functions/classes
- Clear folder structure reflecting architecture
- Split a file when it contains independently changing responsibilities or creates material navigation, coupling, or verification cost; retain a cohesive file when splitting would add avoidable coupling or navigation cost
Commenting Principles
Default: code first
Names, types, and structure are the primary medium. A comment earns its place only by carrying information the code itself cannot express. When in doubt, improve the name instead of adding a comment.
The test for every comment
A comment is justified only if it answers one of these:
- Why: reasoning, trade-off, or constraint behind a non-obvious decision
- Limitation / edge case: a boundary a reader cannot infer from the code
- Public API contract: behavior, inputs, outputs of an exported interface
One comment per decision. If a comment restates what the names and control flow already show, delete it and rename instead.
Comment Scope
- Comment the why, limits, and public contracts (per the test above); let names and structure carry everything else, including the "how"
- Record historical context in version control commit messages, not in comments
- Delete commented-out code (retrieve from git history when needed)
Comment Quality
- Base comments on stable rationale, limits, and contracts rather than dates, versions, temporary state, or references to documents and their sections, which drift as those documents change
- Update comments when changing code
- Use proper grammar and formatting
- Write for future maintainers
Refactoring Approach
Safe Refactoring
- Small steps: Make one change at a time
- Maintain working state: Keep tests passing
- Verify behavior: Run tests after each change
- Incremental improvement: Make the smallest sufficient improvement in each increment
Refactoring Triggers
- Code duplication (DRY principle)
- Functions that contain independently changing responsibilities or obscured control flow
- Complex conditional logic
- Unclear naming or structure
Security Principles
Secure Defaults
- Store credentials and secrets through environment variables or dedicated secret managers
- Use parameterized queries (prepared statements) for all database access
- Use established cryptographic libraries provided by the language or framework
- Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators
- Encrypt sensitive data at rest and in transit using standard protocols
Input and Output Boundaries
- Validate all external input at system entry points for expected format, type, and length. External input includes request data, external service responses, model or tool output, and stored data whose writer is untrusted or whose consumer needs a guarantee the store does not make
- When a change alters a boundary where external content or model output selects a tool's action, target, or destination, verify that those values cannot exceed the operation scope and access rights already granted to the caller
- Encode output appropriately for its rendering context (HTML, SQL, shell, URL)
- Return only information necessary for the caller in error responses; log detailed diagnostics server-side
Access Control
- Apply authentication to all entry points that handle user data or trigger state changes
- Verify authorization for each resource access, not only at the entry point
- Grant only the permissions required for the operation (files, database connections, API scopes)
- For changes involving identity or protected resources, prioritize authentication and per-resource authorization review
For concrete detection patterns used by security review, see references/security-checks.md.
References
- references/frontend.md: read when implementing, reviewing, or fixing React/TypeScript code
Documentation Creation Criteria
This file holds the routing decision: which documents a change requires and where they live. What to write inside one is defined by its template, linked from Storage Locations.
What Each Document Fixes
Each document fixes one class of decision that the repository alone cannot supply. An unfilled section becomes a guess made later by the consumer named below, with no record of what was assumed.
-
PRD — Fixes the business outcome and the acceptance criteria later work traces to. Its AC IDs are the traceability keys that the Design Doc, UI Spec, and test selection reuse; without them each consumer re-derives requirements from prose and the link between a test and the value it protects is lost. Implementation details belong to the Design Doc, selection rationale to an ADR, phases and task breakdown to the Work Plan. Later design, review, and test selection treat its content as governing, so a precondition held outside the repository change, such as release execution or organizational approval, appears in it only when the user's wording raises it.
-
ADR — Records one durable technical choice and the options it beat, so later work can tell a deliberate decision from an accident. Without it a future change either re-runs the same comparison or silently reverses it.
Acceptedrecords the currently selected means, not an obligation to retain it: when later evidence supports a smaller sufficient choice, update or supersede the decision while the outcome, desired-future requirements, and non-goals remain true. End-to-end implementation design belongs to the Design Doc, schedule and repository tasks to the Work Plan. -
UI Spec — Records screen structure, transitions, component/state contracts, and visual acceptance before components exist, so decomposition is decided before implementation instead of per-component during it. Create one when those decisions remain open; reuse an approved UI Spec or go straight to the Design Doc when one evident repository-supported pattern already determines them. Technical implementation and API contracts belong to the Design Doc.
-
Design Doc — Records the complete implementation design for the scope of the requirements: flows, contracts, change impact, and verification strategy. Task execution treats it as the primary technical baseline, so implementation does not silently invent missing How. The same baseline turns anything written in it into planned and implemented work, so release execution, production operation, and other work outside the repository change stay out of it; a requirement that describes such work is met by designing the capability it uses. When repository evidence invalidates technical How while the outcome, desired-future requirements, and non-goals remain true, correct the implementation and the affected technical artifact through their owning workflow without reopening product requirements. Technology selection rationale belongs to an ADR, schedule and assignments to the Work Plan.
-
Work Plan — Fixes task order, dependencies, executable verification, and the earliest vertical proof point. Without it task order follows file layout rather than dependency, and integration risk moves to the end of the work. Design detail is referenced from the Design Doc rather than restated. Each task is repository work the executor completes and verifies during implementation using repository artifacts and its own output.
Creation Decision Matrix
| Structural Scale | Base Documents | Creation Order |
|---|---|---|
| Small | None | Direct implementation |
| Medium | Design Doc → Work Plan | Start with Design Doc |
| Large | PRD → Design Doc → Work Plan | Continue after PRD approval |
Build one path in this order:
- Select the base path from Structural Scale.
- Insert an applicable UI Spec immediately before the Design Doc.
- One or more qualifying ADR decision points insert an ADR batch immediately before the Design Doc. A qualifying decision point sets the scale floor to Medium.
Structural Scale
Classify the decision burden, not repository layout. File count is supporting evidence only.
| Scale | Structural condition |
|---|---|
| Small | One coherent outcome has one evident repository-supported implementation within one responsibility boundary and no unresolved durable choice |
| Medium | One coherent outcome coordinates across a boundary or requires investigation of a potentially durable choice |
| Large | Multiple independently valuable outcomes require separate design decisions |
A qualifying ADR decision point sets the floor at Medium because it creates a durable decision. One coherent outcome remains Medium when it crosses multiple layers; Large requires independently valuable outcomes with separate design decisions.
ADR Decision Filters
Apply the Choice filter, then the Durability filter, to each technical topic inside the implementation scope. Apply them independently from Structural Scale, and check existing ADRs first.
- Choice requires judgment — current requirements, accepted decisions, and representative repository evidence support at least two credible, materially distinct options whose selection requires comparison.
- Decision is durable — choosing among those options materially changes responsibility, dependency direction, a shared contract, persistence, a technology dependency, reversibility, or lifecycle cost that future work must preserve or understand.
Create one ADR for each topic that passes both filters, and review the complete batch together. Treat choices as one decision point when they must be selected or reconsidered together; separate independently revisitable choices.
Qualifying durable choices include:
- introducing or replacing a technology, library, platform, storage model, or external dependency;
- changing ownership, dependency direction, a trust boundary, or a shared public contract when credible alternatives exist;
- replacing an accepted architecture decision with a different durable choice that passes both filters;
- choosing an irreversible or high-cost-to-reverse data or compatibility strategy.
A local contract, data-flow, state, or component change belongs in the Design Doc when it follows an accepted design, has one evident repository-supported implementation, or remains cheaply reversible. Counts of files, consumers, nesting levels, states, steps, and asynchronous operations are supporting evidence rather than ADR criteria. Only the qualifying decisions above create ADRs; generic technical concerns, operational possibilities, and rejected activities can only support that determination.
Storage Locations
| Document | Path | Naming Convention | Template |
|---|---|---|---|
| PRD | docs/prd/ | [feature-name]-prd.md | prd-template.md |
| ADR | docs/adr/ | ADR-[4-digits]-[title].md | adr-template.md |
| UI Spec | docs/ui-spec/ | [feature-name]-ui-spec.md | ui-spec-template.md |
| UI Spec Assets | docs/ui-spec/assets/{feature-name}/ | Prototype code files | - |
| Design Doc | docs/design/ | [feature-name]-design.md | design-template.md |
| Work Plan | docs/plans/ | YYYYMMDD-{type}-{description}.md | plan-template.md |
| Task File | docs/plans/tasks/ | {plan-name}-task-{number}.md | task-template.md |
*Note: Work plans are excluded by .gitignore
References
Each template defines the content, structural elements, and diagram criteria for its document: prd-template.md, adr-template.md, ui-spec-template.md, design-template.md, plan-template.md, task-template.md
External Resource Context
Purpose
Repository evidence does not contain every external resource surrounding a system. This skill captures, in a deterministic location, the access methods to resources outside the repository so downstream work (design, planning, implementation, review) can reach them without repeatedly rediscovering access details.
Resources covered: design origin (where the canonical visual specification lives), design system (component library and tokens), guidelines (usage docs, accessibility rules), visual verification environment (how to confirm rendering), database schema source, migration history, secret store location, API schema source (OpenAPI / proto / GraphQL SDL), mock environment, IaC source, environment configuration.
Storage Locations (Two-Tier)
| Tier | Location | Holds | Update Frequency |
|---|---|---|---|
| Project | docs/project-context/external-resources.md | Environment-stable facts: which resources exist for this project and how to access them (URL, MCP name, file path, command) | Rare — only when the project's environment changes |
| Feature | ## External Resources Used section inside the relevant UI Spec or Design Doc | The subset of project-tier resources actually used by this feature, plus feature-specific identifiers (e.g., a specific node id within the design tool, a specific endpoint path) | Per feature |
Single Source of Truth Rule
The project tier owns environment facts. Feature-tier sections list only feature-specific identifiers (node id within the design source, specific endpoint path within the API, specific IaC module name) and reference project-tier entries by label; URLs, MCP names, and access commands remain in the project-tier file. When the environment changes, only the project-tier file is updated.
Example feature-tier entry uses the table format defined in references/template.md: a row with the project-tier label in the first column and the feature-specific identifier in the second column.
Reference Protocol (For Downstream Consumers)
Before investigating the repository for an external fact, check whether it is already recorded:
- Read
docs/project-context/external-resources.md(if present) to learn what is available and how to access it. - Read the target UI Spec or Design Doc's
## External Resources Usedsection for feature-specific identifiers. - Use the access method declared in the project tier (e.g., the named MCP, the URL, the file path) to fetch the actual resource content.
When the file is absent or the resource is unreachable, continue from governing and repository evidence. Each consumer records the limitation in its applicable output.
Capturing and Updating Records
Capture only resources needed by the current decision. Reuse supplied access details and repository records, verify them within current authority, and ask only for missing information that prevents that decision. Follow references/hearing.md for evidence, questions and storage.
Output Format
Use references/template.md for a compact project record. Preserve existing labels referenced by consumers; include only relevant entries with their access details and source evidence.
For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context).
References
- references/hearing.md — Decision-specific capture and storage
- references/frontend.md — Frontend domain axes
- references/backend.md — Backend domain axes
- references/api.md — API contract domain axes
- references/infra.md — Infrastructure domain axes
- references/template.md — Project-tier and feature-tier structure templates
Implementation Strategy Selection Framework (Meta-cognitive Approach)
Meta-cognitive Strategy Selection Process
Phase 1: Decision-Sufficient Current State Analysis
Core Question: "What does the existing implementation look like?"
Analysis Framework
Architecture Analysis: Responsibility separation, data flow, dependencies, technical debt
Implementation Quality Assessment: Code quality, behavior-relevant test evidence, performance, security
Historical Context Understanding: Current form rationale, past decision validity, constraint changes, requirement evolution
Meta-cognitive Question List
- What is the true responsibility of this implementation?
- Which parts are business essence and which derive from technical constraints?
- What dependencies or implicit preconditions are unclear from the code?
- What benefits and constraints does the current design bring?
Stop when the current-state facts that could change responsibility, reuse, option validity, total complexity, a contract, or verification have been checked; find existing code as coding-principles Reference Representativeness describes.
Phase 2: Design Convergence
Complete these steps in order before selecting an implementation strategy:
- Existing-Surface Baseline: Form the simplest end-to-end path that delivers the current outcome through existing responsibilities. Explicit requirements and accepted decisions are binding; suggested mechanisms remain candidates.
- Evidence Check: Test that path against current requirements, verified constraints, observed in-scope problems, and evidence-backed material risks. Keep only the unmet conditions that can change the selected design. Where the requirements leave a quality level unset, such as performance, freshness, consistency, availability, or protection beyond the required trust boundary, test against the lowest level that still delivers the outcome and record it as the selected level.
- Targeted Comparison: For each unmet condition, test reuse, derivation from existing data, on-demand computation, or responsibility at the current caller or boundary before adding design surface. Compare viable choices by total complexity across the dimensions that materially differ: user decisions, settings, modes, concepts, outputs, persistent state, implementation paths, UX, runtime, implementation, testing, documentation, and maintenance. A second implementation of a responsibility that already has an owner with the same contract and change reason, including one added earlier in the same change, adds design surface; reusing or relocating that owner removes it. Select the lowest-total-complexity choice that satisfies the condition.
- Subtraction Check: Remove each proposed addition and re-test its governing condition. Retain it only when the outcome, a required boundary, or necessary proof becomes unmet at its origin (a requirement, an accepted decision, or a repository rule or contract); a criterion, invariant, or constraint that a workflow artifact derived from that origin is narrowed to what the origin requires instead.
Classify supporting claims as observed, inferred, or unknown. Route an unknown that blocks the next step as an exact evidence prerequisite; the caller's value-boundary and irreversible-action gates determine whether user interaction is required.
Candidate paths and rejected additions remain active analysis. The durable output is the Selected Design: the complete chosen path plus evidence for each added design surface and the condition that fails when it is removed. An accepted ADR may retain alternatives as decision history. An implementer uses the same convergence check without producing a separate artifact.
Phase 3: Strategy Exploration and Creation
Core Question: "When determining before → after, what implementation patterns or strategies should be referenced?"
Strategy Discovery Process
Direct Strategy: Smallest repository-supported change that satisfies the accepted requirements and constraints
Repository Alternatives: Existing patterns that materially differ in migration, dependency order, or verification boundary
External Research: Official/current sources only when repository evidence cannot resolve a time-sensitive capability, compatibility, or dependency decision
Reference Strategy Patterns
Legacy Handling Strategies:
- Strangler Pattern: Gradual migration through phased replacement
- Facade Pattern: Complexity hiding through unified interface
- Adapter Pattern: Bridge with existing systems
New Development Strategies:
- Feature-driven Development: Vertical implementation prioritizing user value
- Foundation-driven Development: Foundation-first construction prioritizing stability
- Risk-driven Development: Prioritize addressing maximum risk elements
Integration/Migration Strategies:
- Proxy Pattern: Transparent feature extension
- Decorator Pattern: Phased enhancement of existing features
- Bridge Pattern: Flexibility through abstraction
Use these patterns only when their named migration or dependency problem exists. Start with the direct strategy. Compare an alternative when it would materially change risk, rollout, compatibility, or the early verification point. Keep the option set limited to patterns that produce one of those material differences.
Phase 4: Material Risk Assessment and Control
Core Question: "What risks arise when applying this to existing implementation, and what's the best way to control them?"
Evaluate only risk categories for which current evidence can change the strategy, public contract, rollout, rollback, or verification boundary.
Conditional Risk Categories
Technical Risks: System impact, data consistency, performance degradation, integration complexity
Operational Risks: Service availability, deployment downtime, process changes, rollback procedures
Phase 5: Decision-Relevant Constraint Compatibility
Core Question: "What are this project's constraints?"
Check only constraints evidenced by the governing requirements, repository, external contracts, or current environment that can change the selected strategy or verification boundary.
Conditional Constraint Categories
Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets
Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods
Phase 6: Implementation Approach Decision
Select the implementation approach that directly fits the verified dependency and delivery constraints:
Vertical Slice (Feature-driven)
Characteristics: Vertical implementation across all layers by feature unit Application Conditions: Default when an end-to-end value unit can be delivered and verified independently. Data-model sharing and layer breadth are supporting evidence, not substitutes for independent deliverability Verification Method: End-user value delivery at each feature completion
Horizontal Slice (Foundation-driven)
Characteristics: Phased construction by architecture layer Application Conditions: Use when a common foundation blocks consumer work or must pass stability/compatibility verification before dependent slices can proceed. Materially shared dependency ownership across multiple consumers is a signal to evaluate this approach Verification Method: Integrated operation verification when all foundation layers complete
Hybrid
Characteristics: Flexible combination according to project characteristics Application Conditions: Use when a verified foundation step is required first and later work can proceed as independently verifiable value slices. Resolve blocking requirement ambiguity before selecting the implementation approach Verification Method: Verify at appropriate L1/L2/L3 levels according to each phase's goals
Phase 7: Decision Rationale Documentation
Record in the applicable implementation or design decision record:
- Selected strategy name and characteristics
- Current evidence and total-complexity basis for added design surface
- Controls for each material risk activated in Phase 4
- Compatibility with each decision-relevant constraint activated in Phase 5
- Verification level (L1/L2/L3) and integration point definition
Alternatives remain active analysis unless an accepted ADR owns them as decision history.
Verification Level Definitions
Priority for completion verification of each task:
- L1: Functional Operation Verification - Operates as end-user feature (e.g., search executable)
- L2: Test Operation Verification - Tests that prove the changed behavior pass
- L3: Build Success Verification - Code builds/runs without errors
Priority: L1 > L2 > L3 in order of verifiability importance
Integration Point Definitions
Define integration points according to selected strategy:
- Strangler-based: When switching between old and new systems for each feature
- Feature-driven: When users can actually use the feature
- Foundation-driven: When all architecture layers are ready and E2E tests pass
- Hybrid: When individual goals defined for each phase are achieved
Quality Checks
- Confirm Phase 1 identifies the current responsibility, dependency path, and historical constraints before selecting a strategy
- Confirm Phase 2 produces one complete Selected Design and every added design surface maps to current evidence, lower-surface insufficiency, and a failed condition under subtraction
- Confirm Phase 4 records concrete controls for every evidenced material risk; no entry is required for an inapplicable category
- Confirm Phase 5 checks every evidenced constraint that can change strategy selection or verification; no entry is required for an inapplicable category
- Confirm Phase 7 records the selected strategy, its total-complexity basis, and the early verification point; alternatives appear only in an accepted ADR
Guidelines for Meta-cognitive Execution
- Leverage Known Patterns: Use a pattern when its problem and trade-off match the observed repository state
- Conditional External Research: Use official/current sources when a time-sensitive capability, compatibility, or dependency decision remains unresolved after repository inspection
- Apply 5 Whys: Pursue root causes to grasp essence
- Multi-perspective Evaluation: Evaluate current state, convergence, risk, and constraints before selecting the implementation approach
Integration and E2E Skeleton Contracts
Test Lanes
| Lane | Observable boundary | Dependencies |
|---|---|---|
integration | Interactions within a process, including framework-rendered UI and module/API handlers | Real participating components; mock only outside the claimed boundary |
fixture-e2e | Actual UI behavior in a real browser with deterministic fixtures | Fixtures may replace dependencies outside the claimed boundary |
service-integration-e2e | Outcome depends on actual cross-service interaction or persistence | Required local services and stores are real; stubs only outside that proof boundary |
Test Skeleton Specification
Required Comment Patterns
Each test MUST include the following annotations:
AC: [Original acceptance criteria text]
Behavior: [Trigger] → [Process] → [Observable Result]
@lane: integration | fixture-e2e | service-integration-e2e
@dependency: none | [component names] | full-system
Selection evidence: [required claim, uncovered failure, and why cheaper existing proof is insufficient]
Use the project's comment syntax to wrap these annotations (e.g., // for C-family, # for Python/Ruby/Shell).
Selection evidence serves test selection and planning, so the implementing task removes it when it makes the test executable.
Verification Items (Optional)
When verification points need explicit enumeration:
Verification items:
- [Item 1]
- [Item 2]
Test File Naming Convention
- Integration tests:
*.int.test.*or*.integration.test.* - fixture-e2e tests:
*.fixture.e2e.test.*(or organize undertests/e2e/fixture/) - service-integration-e2e tests:
*.service.e2e.test.*(or organize undertests/e2e/service/)
The test runner or framework in the project determines the appropriate file extension. Repos that already use a single *.e2e.test.* convention may keep it as long as each file declares @lane: in its header — the lane annotation is the source of truth for routing.
Route Parity for Shared Mutations
When multiple routes reach the same mutation, compare validation, classification, resource bounds, and read/parse/mutation/reporting order. A difference becomes a proof obligation when it can violate an authoritative contract or expose a material bypass in the changed boundary. Reuse existing proof or add the smallest test that detects that failure.
LLM-Friendly Context
The goal is stable downstream execution: the next consumer should know what to read, what to do, what counts as success, and which unresolved decisions can change the result.
Core Rules
-
Use positive, executable instructions
- State what the next consumer should do.
- Convert quality policies into positive criteria.
- Keep a prohibition only when it protects an irreversible boundary or shipped contract. Name the protected condition and the allowed action.
- Example: "Preserve existing public API behavior across the documented compatibility cases."
-
Make vague instructions concrete
- Clarify wording when plausible interpretations would change the outcome, scope, authority or proof. Supply purpose, evidence and selection criteria for reversible choices; reserve exact selections for actual consumer contracts and user-owned decisions.
- Terms that often need clarification when they leave a decision to the next consumer:
appropriate,proper,related,existing behavior,optional,as needed,if needed,per convention, unresolved alternatives,TBD,placeholder.
-
Specify output shape
- Use the sections, fields, table columns, JSON keys, or checklist items the consumer uses.
- For handoffs, include only produced artifact paths and status fields that control the next transition.
-
Provide the smallest sufficient context
- Sufficient means sufficient for the assigned action, not complete background: every item you include is consumed by that action or by the result it must produce.
- Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions that action consumes.
- Prefer concrete file paths and section hints over broad module names.
- Follow references while they can change an in-scope decision, action, or verification result.
-
Decompose complex work into verifiable steps
- Expose real dependencies and their completion evidence. Let independent reversible work follow the route suited to the task.
- Each step needs a checkpoint: what evidence proves it is complete.
-
Permit uncertainty explicitly
- Resolve missing operational detail from referenced artifacts and repository evidence before treating it as unresolved.
- Record remaining uncertainty with its effect, required input, and decision owner. Make reversible repository-local choices when governing evidence resolves them.
-
Keep constraints proportionate
- Add only constraints that reduce ambiguity or preserve a real requirement.
- Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear.
- Interpret minimal as the least downstream complexity that fully solves the problem. An explicit user diff limit is a constraint; otherwise necessary corrections are not bounded by a line count.
Rewrite Patterns
Use these rewrites before treating a prompt, handoff, or artifact as complete.
| Ambiguous form | Rewrite as |
|---|---|
optional used as an unresolved choice | Required, omitted, or required only under a named condition |
| Alternatives whose choice changes a protected outcome | The governing constraint or unresolved owner decision; for reversible choices, purpose, evidence and selection criteria |
as needed / if needed | The triggering condition and required action |
per convention | The file, function, test, or documented convention to follow |
related files | Specific paths, globs, or search hints |
existing behavior | The observable behavior, source file, test, API response, or UI state to preserve |
placeholder | Exact temporary value/behavior, allowed dependencies, and verification expectation |
TBD used as a placeholder for required information | A blocking unresolved item with owner, required input, and decision effect |
appropriate / proper | A measurable criterion or checklist |
Handoff Checklist
Before sending a prompt or artifact to another consumer, verify:
- The target action is explicit.
- Required input paths, source artifacts, and decision-relevant facts are named.
- Every included context item is consumed by the target action or its required result.
- Accepted decisions and constraints use one canonical wording.
- Output format or expected status fields are specified.
- Success criteria are observable.
- Outcome-relevant ambiguities are resolved or assigned to their decision owner; harmless execution flexibility remains.
- Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative.
- The next consumer can complete its scope from the supplied purpose, sources, criteria, and evidence, or return the exact unresolved decision and owner.
Generated Artifact Checklist
Before writing or finalizing a generated document:
- Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists.
- Every executable instruction names the target, action, and expected result.
- Verification steps say what to run or observe and what result proves success.
- Each instruction states the allowed action; each retained prohibition names the protected condition and allowed alternative.
- If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning.
- If downstream work is blocked by missing information, the artifact records the missing input, decision owner, and effect.
Requirement Convergence
Purpose
Requirements arrive bloated, ambiguous, or aimed at the wrong outcome. A capable model reconciles all three into a coherent plan and builds it faithfully — delivering exactly what was asked for when what was asked for was wrong.
This skill converges what to build. How to build it, and which documents the change requires, come after the what.
Convergence Fields
| Field | Pass condition |
|---|---|
outcome | One observable result. A requirement that does not serve it is excess. |
requirements[] | Every build-relevant item labeled current-state or desired-future. |
nonGoals[] | Authored by the user, or the user stated there are none. |
cost | A band with the repository and lifecycle evidence that places it, plus the unknowns that remain. |
cost is a rough band, not the effort estimate a work plan schedules against; requirements cannot support person-days. Its unknowns carry more decision weight than its size.
Classify from the user's own retained wording, not from an analyzer's restatement of it: wording that asks for an evaluation, describes a speculative idea, or suggests a mechanism stays in active convergence context as a judgment-only candidate. requirements[] and durable documents receive a candidate only after explicit user confirmation.
Each field carries a readiness label: ready, weak, or weak-but-explicit (weak, and the user agreed to leave it unresolved). Only the user sets weak-but-explicit. Requirements are converged when every applicable field is ready or weak-but-explicit.
Judgment rules per field: references/criteria.md.
Hearing Protocol
Run the hearing after scope analysis has produced the facts needed to judge the convergence fields. The workflow using this skill owns the interaction method and routing; this skill defines the hearing content and pass conditions.
Register these steps before starting and record each step's evidence as it completes:
| Step | Action | Completion evidence |
|---|---|---|
| 1 | Render the Scope Confirmation below, asking only about the fields below ready | Each fact cites the analysis output it came from, and User decisions holds one question per field below ready |
| 2 | Record each answer as that field's value | The value uses wording the user supplied, not wording the hearing offered |
| 3 | Re-ask once when a recorded value still fails its pass condition, then mark the field weak-but-explicit when the user agrees to leave the second answer as it stands | Two recorded answers, or the user's agreement to stop |
| 4 | Hand the record to the step that judges the fields | An updated record returned from that step |
Step 2's evidence is what keeps the hearing reviewable: a value restating the hearing's own candidates fails it, so the user's judgment survives however the question was put.
Scope Confirmation
Render this shape at every requirements confirmation stop, whether or not the hearing ran, using only what can change the user's requirement decision or the workflow route.
| Section | Contents |
|---|---|
| User-selected scope | The requirements and exclusions the user has already selected, in the user's wording |
| Decision evidence | Each material observed fact with its source, followed by what that fact can change about scope, outcome, or cost |
| User decisions | One question per convergence field below ready (Hearing Protocol Step 1), followed by the scope, outcome, or cost effects of its materially different answers |
| Workflow | Rough cost band with the unknowns that remain, Structural Scale, and the selected document and workflow route |
Keeping the first three sections separate is what makes the decision informable: merged, the reader cannot tell which line is the user's own selection, which is a repository observation, and which is still open.
Only an explicit user answer moves an item from User decisions into User-selected scope. Because Step 2 records the user's own wording, pose each open decision as a question and let the user supply its answer. The orchestrator owns Workflow and presents it as a selected route.
Storage Protocol
| Carrier | Holds | Written by |
|---|---|---|
| The convergence record in the judging step's output | Every field with its readiness label | The judging step |
PRD Success Criteria and Future / Out of Scope | outcome; user-authored nonGoals | The PRD production step |
Design Doc Requirement Convergence | The same when no PRD exists, and the fields left weak-but-explicit in every case | The Design Doc production step |
A flow that produces neither document carries the record in its own context to the next step.
Reference Protocol (For Downstream Consumers)
- Read the convergence record from the prompt.
- Treat
nonGoalsas excluded from the current change anddesired-futurerequirements as buildable scope. Evaluation requests, speculative ideas, prescribed mechanisms, and agent-proposed capabilities that were not promoted create no downstream obligation; an accepted ADR may retain evaluated options as decision history. - Treat a
weak-but-explicitfield as a recorded open question rather than a settled decision. When work depends on it, return the missing decision and its effect to the owning workflow.
Quality Checklist
- Scope facts were presented before questions were asked
-
nonGoalscame from the user, or the user stated there are none - Every applicable field is
ready, orweak-but-explicitby the user's agreement
References
- references/criteria.md — judgment rules per field, cost inputs, challenge intensity, solution-in-disguise test
Language-Agnostic Testing Principles
Tests here guarantee accepted behavior, and the next agent reads every existing test as a requirement to preserve. A brittle, duplicated, or implementation-shaped test therefore becomes a false requirement: it gets worked around, and the workaround leaves debt in the implementation. Keep the set of tests whose proof is worth its maintenance.
Test Selection
- Prove accepted behavior by default through integration and E2E tests at the boundary users and callers observe. Add a unit test for logic whose cases one representative boundary test cannot prove, such as calculations, parsing, or branching rules.
- Each behavioral claim is owned by one test: such logic by its unit test, other behavior by the test at the narrowest integration or E2E boundary where it is observable. A test at a wider boundary or in a variant (viewport, device, role) proves what that boundary or variant adds, such as wiring, mapping, persistence, rendering, or navigation, and keeps at most one representative case of a rule owned elsewhere.
- Determine the required proof boundary from the accepted outcome before minimizing tests. An outcome delivered through an application or service entry point includes the relevant production composition, such as routing, providers, state ownership or adapters. An isolated component test or a test-built substitute composition does not prove that wiring. Reuse proof that traverses it, or select a test that will; choose the harness by what it must observe, not by component count or a lane quota. A disconnected action, lost state update or broken transition can remain invisible to tests below that boundary. Explicitly component-scoped outcomes retain their component boundary.
- Treat coverage as a diagnostic signal for finding untested areas, not a target; any CI threshold is the project's config, not a quality goal in itself.
- Use project-configured speed budgets when present. Otherwise investigate test speed only when observed feedback or CI cost is material to the current outcome; retain slower tests when their proof boundary requires it.
Test Design Rules
- Structure each test as Arrange, one Act, and Assert; multiple assertions may prove one behavior.
- Follow the repository's test naming convention and name the condition and observable outcome.
- Exercise behavior through a public or integration boundary. Assertions verify return values, outputs, errors, or state changes rather than private implementation.
- Use independently derived literal, property, approved snapshot, or fixture expectations. An implementation-derived oracle cannot detect the same implementation defect.
- Keep each test's expected outcome unconditional. Table-driven or property-based cases are acceptable when each case is reported distinctly and uses an independent oracle.
- Cover accepted boundary and error behavior; derive cases from the contract instead of adding generic edge-case permutations.
- Each test creates and cleans up its own state, passes in isolation and any order, and controls time or randomness that affects its result.
- Keep tests executable. Fix or remove tests that no longer describe accepted behavior; restore tests disabled only to bypass a failure.
Mock and Boundary Rules
- Mock direct external I/O boundaries; keep internal business logic and the boundary under test real.
- Use the existing application-owned adapter as the mock boundary. Introduce an adapter only when external I/O, an unstable contract, or required substitution cannot be controlled through the current design.
- Keep mock behavior limited to the contract needed by the test.
Data Layer Testing
Mock-based tests are sufficient when data access is only a dependency of the behavior under test. Verify against the project's real database engine or its accepted equivalent when the subject is a query, repository implementation, schema constraint, or migration compatibility. Resolve the test environment from repository configuration; when no representative environment exists and adding one is outside the approved work, report the missing verification decision.
Cross-check data-access code against the schema source named in the Design Doc or repository configuration. Schema-source verification is required to prove table, column, type, constraint, or dialect compatibility; successful mocks prove behavior only at the mocked boundary.
Verification Requirements
Capability Probe Postconditions
A capability probe passes when it uses the consumer's boundary and asserts the exact property that consumer needs. Command success, import success, or object existence is setup evidence.
Test Organization
Follow the repository's established test paths, runner routing, and naming. When establishing an approved new convention, separate test types only when their setup, runner, or environment differs.
Regression Testing
- Add a regression test for every reproducible behavior bug fix. When executable reproduction is impossible, record the reason and the alternative static, contract, or environment evidence that prevents recurrence.
- Before behavior-preserving changes to uncharacterized legacy code, establish passing characterization evidence and rerun it after the change.
References
- references/frontend.md: read when writing, changing, or reviewing component, hook, or UI integration tests
- references/e2e.md: read when writing, changing, or reviewing browser E2E tests
Sponsors
Details
- Marketplace
- shinpr/claude-code-workflows
- Source
- dev-skills
- Author
- Shinsuke Kagawa
- Category
- Community
- License
- MIT
- Keywords
- skills, best-practices, coding-standards, testing, design-docs, development, quality