Phase 1-3: Add memory, skills, and improvement systems
- memory/: cross-session project memory with decisions, lessons, failures, architecture, and sessions categories. Each has format templates and lifecycle documentation. - skills/: 12 reusable specialized methodologies (tdd, systematic-debugging, architecture-design, code-review, security-review, repository-analysis, failure-analysis, refactoring, test-analysis, incident-investigation, browser-automation, research). Each has frontmatter and methodology sections. - improvements/: proposal-based improvement system requiring human approval. - scripts/memory-lifecycle.sh: deterministic memory operations (recall, store, list, search, sessions, cleanup). - scripts/test-memory-system.sh: 12 structural tests for all new systems. - orchestrator.md: added Memory Recall stage, Learning and Memory Storage stage, Improvement Proposals workflow, memory/skills rules, and 3 new actions (A23-A27) to the action catalog. Updated behavioral acceptance test and state separation model. - All 12 subagents: added Memory & Skills Awareness sections with recall and store instructions. - docs/AGENT_ARCHITECTURE.md: documented memory, skills, and improvements systems (sections 12-14). Updated action count (27), state model, and remaining weaknesses. - README.md: documented new systems, updated repository layout, added test-memory-system.sh documentation. All 39 tests pass (16 architecture + 12 memory + 11 bootstrap).
This commit is contained in:
Your Name
@@ -0,0 +1,95 @@
|
||||
# Skills System
|
||||
|
||||
## Purpose
|
||||
|
||||
Skills provide reusable, specialized capabilities that agents can load when needed.
|
||||
Instead of duplicating instruction sets across every agent, skills centralize
|
||||
domain-specific knowledge and procedures.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
skills/
|
||||
├── SKILLS.md # This file — index and loading rules
|
||||
├── tdd/ # Test-Driven Development
|
||||
│ └── SKILL.md
|
||||
├── systematic-debugging/ # Systematic debugging methodology
|
||||
│ └── SKILL.md
|
||||
├── architecture-design/ # Architecture decision process
|
||||
│ └── SKILL.md
|
||||
├── code-review/ # Code review checklist and process
|
||||
│ └── SKILL.md
|
||||
├── security-review/ # Security review methodology
|
||||
│ └── SKILL.md
|
||||
├── repository-analysis/ # Repository exploration methodology
|
||||
│ └── SKILL.md
|
||||
├── failure-analysis/ # Failure investigation methodology
|
||||
│ └── SKILL.md
|
||||
├── refactoring/ # Refactoring principles and patterns
|
||||
│ └── SKILL.md
|
||||
├── test-analysis/ # Test coverage and quality analysis
|
||||
│ └── SKILL.md
|
||||
├── incident-investigation/ # Incident response methodology
|
||||
│ └── SKILL.md
|
||||
├── browser-automation/ # Browser automation patterns
|
||||
│ └── SKILL.md
|
||||
└── research/ # Research methodology
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
## Loading Rules
|
||||
|
||||
1. The Orchestrator identifies which skill(s) a task requires
|
||||
2. The Orchestrator includes the skill path in the agent's dispatch brief
|
||||
3. The agent reads the skill file before beginning work
|
||||
4. The agent applies the skill's procedures to the task
|
||||
|
||||
## Skill Format
|
||||
|
||||
Each skill file contains:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <skill-name>
|
||||
description: <what this skill provides>
|
||||
version: "1.0"
|
||||
owner: <which agent maintains this skill>
|
||||
prerequisites: <what must be true before using this skill>
|
||||
---
|
||||
|
||||
# <Skill Name>
|
||||
|
||||
## When to use this skill
|
||||
## Core methodology
|
||||
## Step-by-step procedure
|
||||
## Common pitfalls
|
||||
## Evidence requirements
|
||||
## Exit criteria
|
||||
```
|
||||
|
||||
## Agent-Skill Mapping
|
||||
|
||||
| Agent | Primary Skills | Optional Skills |
|
||||
|-------|---------------|-----------------|
|
||||
| Explorer | repository-analysis, research | browser-automation |
|
||||
| Detective | systematic-debugging, failure-analysis | incident-investigation |
|
||||
| Architect | architecture-design | code-review, security-review |
|
||||
| Builder | tdd, refactoring | code-review |
|
||||
| Tester | tdd, test-analysis | failure-analysis |
|
||||
| Reviewer | code-review, security-review | test-analysis, architecture-design |
|
||||
| Maintainer | refactoring | code-review |
|
||||
| Toolsmith | systematic-debugging | — |
|
||||
| Designer | — | research, browser-automation |
|
||||
| Philosopher | — | research |
|
||||
| Writer | — | research |
|
||||
| Workflow Architect | — | — |
|
||||
|
||||
## Customization
|
||||
|
||||
Skills can be extended per-project by adding project-specific sections.
|
||||
When a skill is customized, add a note at the top:
|
||||
|
||||
```markdown
|
||||
> Customized for <project> on YYYY-MM-DD. Original skill preserved in
|
||||
> the agent team repository.
|
||||
```
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
name: architecture-design
|
||||
description: Architecture decision process — structured approach to system design decisions
|
||||
version: "1.0"
|
||||
owner: Architect
|
||||
prerequisites: requirements understood, constraints identified
|
||||
---
|
||||
|
||||
# Architecture Design
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- Deciding system boundaries, interfaces, or component ownership
|
||||
- Evaluating architectural alternatives
|
||||
- Establishing new patterns or constraints
|
||||
|
||||
## Core methodology
|
||||
|
||||
```text
|
||||
UNDERSTAND → IDENTIFY DECISION → GENERATE OPTIONS → EVALUATE → DECIDE → RECORD
|
||||
```
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Understand the context
|
||||
- What problem are we solving?
|
||||
- What are the constraints (technical, organizational, time)?
|
||||
- What existing architecture does this interact with?
|
||||
|
||||
### 2. Identify the decision
|
||||
- What exactly needs to be decided?
|
||||
- What are the boundaries of this decision?
|
||||
- Who are the stakeholders?
|
||||
|
||||
### 3. Generate options
|
||||
- Aim for 2-4 concrete options
|
||||
- Each option should be distinct (not variations of the same idea)
|
||||
- For each: what does it optimize for? What does it sacrifice?
|
||||
|
||||
### 4. Evaluate options
|
||||
For each option, assess:
|
||||
- **Fit**: does it solve the stated problem?
|
||||
- **Complexity**: how much does it add?
|
||||
- **Reversibility**: how hard is it to change later?
|
||||
- **Risk**: what could go wrong?
|
||||
- **Evidence**: what supports this choice?
|
||||
|
||||
### 5. Decide
|
||||
- Choose one option with clear rationale
|
||||
- State what is explicitly out of scope
|
||||
- Identify what would make you revisit this decision
|
||||
|
||||
### 6. Record
|
||||
- Write an ADR in `memory/decisions/`
|
||||
- Update `memory/architecture/` if boundaries change
|
||||
- Link to related decisions
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Deciding without evidence (opinion-driven design)
|
||||
- Over-architecting for imagined future needs
|
||||
- Not recording the decision (lost institutional knowledge)
|
||||
- Ignoring existing patterns (inconsistency)
|
||||
- Making reversible decisions with irreversible processes
|
||||
|
||||
## Evidence requirements
|
||||
|
||||
- Problem statement with constraints
|
||||
- Options considered with trade-offs
|
||||
- Decision rationale
|
||||
- Recording in ADR format
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Decision made and recorded
|
||||
- Alternatives documented with rationale
|
||||
- Impact on existing architecture assessed
|
||||
- Stakeholders can find the decision
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: browser-automation
|
||||
description: Browser automation patterns — web interaction, scraping, and testing
|
||||
version: "1.0"
|
||||
owner: Explorer
|
||||
prerequisites: web technology available, target URL known
|
||||
---
|
||||
|
||||
# Browser Automation
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- Web content needs to be fetched and analyzed
|
||||
- UI behavior needs to be verified
|
||||
- API documentation needs to be read from web sources
|
||||
|
||||
## Core methodology
|
||||
|
||||
```text
|
||||
IDENTIFY TARGET → SELECT TOOL → FETCH/INTERACT → ANALYZE → RECORD
|
||||
```
|
||||
|
||||
## Patterns
|
||||
|
||||
### Content fetching
|
||||
- Use `webfetch` tool for static content
|
||||
- Prefer markdown format for readability
|
||||
- Handle errors and timeouts gracefully
|
||||
|
||||
### Research
|
||||
- Use `websearch` for finding information
|
||||
- Use `webfetch` for reading specific pages
|
||||
- Cite sources with URLs
|
||||
|
||||
### Verification
|
||||
- Fetch expected content
|
||||
- Compare with actual behavior
|
||||
- Document discrepancies
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Assuming content hasn't changed since last fetch
|
||||
- Not handling rate limits
|
||||
- Fetching more than needed (context bloat)
|
||||
- Trusting web content without verification
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Content fetched and analyzed
|
||||
- Sources cited
|
||||
- Findings recorded
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: code-review
|
||||
description: Code review process — systematic review of changes for quality, correctness, and maintainability
|
||||
version: "1.0"
|
||||
owner: Reviewer
|
||||
prerequisites: implementation completed, tests passing
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- Before accepting a completed implementation
|
||||
- When reviewing a pull request or change set
|
||||
- When verifying scope compliance
|
||||
|
||||
## Core methodology
|
||||
|
||||
```text
|
||||
READ CHANGES → CHECK CORRECTNESS → CHECK SCOPE → CHECK TESTS → CHECK DESIGN → CHECK SAFETY → VERDICT
|
||||
```
|
||||
|
||||
## Review checklist
|
||||
|
||||
### Correctness
|
||||
- [ ] Does the code do what it claims?
|
||||
- [ ] Does it handle edge cases?
|
||||
- [ ] Are error paths handled?
|
||||
- [ ] Are there off-by-one errors?
|
||||
|
||||
### Scope compliance
|
||||
- [ ] Does the change match the approved scope?
|
||||
- [ ] Is there unauthorized scope expansion?
|
||||
- [ ] Are only the files that should change actually changed?
|
||||
|
||||
### Tests
|
||||
- [ ] Do tests verify the behavior (not implementation)?
|
||||
- [ ] Are edge cases tested?
|
||||
- [ ] Is there regression test coverage?
|
||||
- [ ] Do tests pass?
|
||||
|
||||
### Design
|
||||
- [ ] Is the code consistent with existing patterns?
|
||||
- [ ] Are interfaces clean and minimal?
|
||||
- [ ] Is there unnecessary complexity?
|
||||
- [ ] Would a future developer understand this?
|
||||
|
||||
### Safety
|
||||
- [ ] Are there security implications?
|
||||
- [ ] Are there performance implications?
|
||||
- [ ] Are there race conditions?
|
||||
- [ ] Are secrets or credentials handled safely?
|
||||
|
||||
### Documentation
|
||||
- [ ] Are public APIs documented?
|
||||
- [ ] Are non-obvious decisions explained?
|
||||
- [ ] Is the change self-documenting?
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Rubber-stamping (approving without reading)
|
||||
- Nitpicking style when correctness matters
|
||||
- Not testing the change locally
|
||||
- Accepting "it works" without evidence
|
||||
- Missing scope creep
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- All checklist items addressed (pass or explain why not)
|
||||
- Findings categorized: BLOCKING / REQUIRED / SUGGESTED / NOTE
|
||||
- Verdict: ACCEPT / ACCEPT_WITH_NOTES / CHANGES_REQUIRED / BLOCKED
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: failure-analysis
|
||||
description: Failure analysis methodology — analyzing system failures to identify patterns and prevent recurrence
|
||||
version: "1.0"
|
||||
owner: Detective
|
||||
prerequisites: failure observed, evidence available
|
||||
---
|
||||
|
||||
# Failure Analysis
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- A failure has occurred and needs to be understood
|
||||
- Recurring failures need pattern analysis
|
||||
- Post-incident review is needed
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Collect evidence
|
||||
- Gather all available evidence: logs, error messages, stack traces
|
||||
- Note the timeline: when did it start, what changed
|
||||
- Identify affected components and users
|
||||
|
||||
### 2. Classify the failure
|
||||
- **Type**: tool / environment / assumption / plan / implementation / test / coordination
|
||||
- **Severity**: critical / high / medium / low
|
||||
- **Scope**: isolated / widespread
|
||||
- **Frequency**: one-time / recurring
|
||||
|
||||
### 3. Root cause analysis
|
||||
- Use the systematic debugging skill for individual failures
|
||||
- For patterns: look across multiple failure records
|
||||
- Ask: "What condition must be true for this failure to occur?"
|
||||
|
||||
### 4. Impact assessment
|
||||
- What was the actual impact?
|
||||
- What was the potential impact?
|
||||
- Were there cascading effects?
|
||||
|
||||
### 5. Resolution
|
||||
- How was it resolved (or is it still open)?
|
||||
- Was the resolution verified?
|
||||
- Are there residual risks?
|
||||
|
||||
### 6. Prevention
|
||||
- What prevents this specific failure from recurring?
|
||||
- What prevents the class of failures from recurring?
|
||||
- Should a Toolsmith safeguard be created?
|
||||
- Should a test be added?
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Stopping at the symptom (not the cause)
|
||||
- Blaming individuals instead of processes
|
||||
- Documenting the fix without documenting the prevention
|
||||
- Not checking for similar patterns elsewhere
|
||||
|
||||
## Evidence requirements
|
||||
|
||||
- Complete failure record in `memory/failures/`
|
||||
- Root cause with evidence
|
||||
- Prevention measures with verification
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Root cause identified
|
||||
- Resolution verified
|
||||
- Prevention documented
|
||||
- Related failures checked for patterns
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: incident-investigation
|
||||
description: Incident investigation — structured response to production or system incidents
|
||||
version: "1.0"
|
||||
owner: Detective
|
||||
prerequisites: incident reported, system accessible
|
||||
---
|
||||
|
||||
# Incident Investigation
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- A production system is failing
|
||||
- Users are reporting issues
|
||||
- Monitoring alerts are firing
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Triage
|
||||
- How severe is the incident?
|
||||
- What is the current impact?
|
||||
- Is it getting worse?
|
||||
|
||||
### 2. Stabilize
|
||||
- Can we restore service quickly?
|
||||
- Is there a safe rollback?
|
||||
- What is the minimal fix?
|
||||
|
||||
### 3. Investigate
|
||||
- Use systematic debugging methodology
|
||||
- Collect evidence while the incident is live
|
||||
- Note timeline of observations
|
||||
|
||||
### 4. Resolve
|
||||
- Apply the fix
|
||||
- Verify the fix works
|
||||
- Monitor for regression
|
||||
|
||||
### 5. Review
|
||||
- Document what happened
|
||||
- Identify root cause
|
||||
- Propose prevention measures
|
||||
- Record in `memory/failures/`
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Jumping to fix without understanding
|
||||
- Not collecting evidence during the incident
|
||||
- Blaming individuals instead of processes
|
||||
- Not following up on prevention
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Service restored
|
||||
- Root cause identified
|
||||
- Prevention measures proposed
|
||||
- Incident recorded in memory
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: refactoring
|
||||
description: Refactoring principles — improving code structure without changing behavior
|
||||
version: "1.0"
|
||||
owner: Builder + Maintainer
|
||||
prerequisites: tests exist and pass, behavior is well-understood
|
||||
---
|
||||
|
||||
# Refactoring
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- Code works but is hard to understand or maintain
|
||||
- Duplication exists that should be extracted
|
||||
- Naming is unclear or misleading
|
||||
- Structure doesn't match the conceptual model
|
||||
|
||||
## Core principle
|
||||
|
||||
**Refactoring changes structure, not behavior.** If you don't have tests, write
|
||||
them first. If you can't verify behavior is preserved, don't refactor.
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Verify baseline
|
||||
- Run the full test suite
|
||||
- Confirm all tests pass
|
||||
- Note the test output (baseline for comparison)
|
||||
|
||||
### 2. Identify the refactor
|
||||
- What specific structural improvement?
|
||||
- What is the expected benefit?
|
||||
- Is this the smallest useful refactor?
|
||||
|
||||
### 3. Make the change
|
||||
- One small step at a time
|
||||
- Run tests after each step
|
||||
- If tests fail, revert and try a smaller step
|
||||
|
||||
### 4. Verify
|
||||
- Run the full test suite again
|
||||
- Compare output to baseline
|
||||
- Verify no behavior change
|
||||
|
||||
### 5. Document
|
||||
- Note what was refactored and why
|
||||
- Update relevant documentation if public interfaces changed
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Refactoring while fixing a bug (mixes two changes)
|
||||
- Not having tests before refactoring
|
||||
- Making large changes in one step
|
||||
- Renaming things that don't need renaming
|
||||
- "While I'm here" scope creep
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Full test suite passes
|
||||
- No behavior change (same inputs, same outputs)
|
||||
- Code is clearer/simpler than before
|
||||
- Change is small enough to review
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: repository-analysis
|
||||
description: Systematic repository exploration — understanding codebase structure, patterns, and conventions
|
||||
version: "1.0"
|
||||
owner: Explorer
|
||||
prerequisites: repo access
|
||||
---
|
||||
|
||||
# Repository Analysis
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- First encounter with a repository
|
||||
- Understanding a new area of a familiar repository
|
||||
- Before architectural or implementation decisions
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Orientation
|
||||
- Read README, package.json/pyproject.toml, or equivalent
|
||||
- Identify the project's purpose, language, and framework
|
||||
- Note the top-level structure
|
||||
|
||||
### 2. Entry points
|
||||
- Find the main entry points (main, index, app)
|
||||
- Trace the execution flow from entry to key functionality
|
||||
- Identify the public API surface
|
||||
|
||||
### 3. Structure
|
||||
- Map the directory structure to logical components
|
||||
- Identify module boundaries and dependencies
|
||||
- Note naming conventions
|
||||
|
||||
### 4. Build & test
|
||||
- Identify the build system and commands
|
||||
- Find the test suite and how to run it
|
||||
- Check for linting, type-checking, CI configuration
|
||||
|
||||
### 5. Conventions
|
||||
- Note coding style (formatting, naming, patterns)
|
||||
- Identify architectural patterns (MVC, layered, etc.)
|
||||
- Check for existing documentation of conventions
|
||||
|
||||
### 6. Dependencies
|
||||
- Review external dependencies
|
||||
- Note version constraints and lock files
|
||||
- Identify any custom or vendored dependencies
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Exploring too broadly (lost in the codebase)
|
||||
- Not recording findings (have to re-explore)
|
||||
- Confusing what exists with what is intended
|
||||
- Not distinguishing generated from hand-written code
|
||||
- Ignoring test files (they reveal intent)
|
||||
|
||||
## Evidence requirements
|
||||
|
||||
- File:line references for key findings
|
||||
- Confidence levels for uncertain findings
|
||||
- Questions for follow-up investigation
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- System map with key files and their roles
|
||||
- Confidence levels for each finding
|
||||
- Open questions listed
|
||||
- Findings recorded in report
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: research
|
||||
description: Research methodology — structured investigation to answer questions
|
||||
version: "1.0"
|
||||
owner: Explorer + Writer
|
||||
prerequisites: question defined
|
||||
---
|
||||
|
||||
# Research
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- A question needs a well-researched answer
|
||||
- Comparing alternatives
|
||||
- Understanding best practices
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Define the question
|
||||
- What exactly are we trying to find out?
|
||||
- What constitutes a good answer?
|
||||
- What are the constraints?
|
||||
|
||||
### 2. Gather sources
|
||||
- Internal: code, docs, memory, agent reports
|
||||
- External: web, documentation sites, official references
|
||||
- Evaluate source reliability
|
||||
|
||||
### 3. Analyze
|
||||
- Compare findings across sources
|
||||
- Identify contradictions
|
||||
- Assess confidence in each finding
|
||||
|
||||
### 4. Synthesize
|
||||
- Combine findings into a coherent answer
|
||||
- Distinguish facts from opinions
|
||||
- State what remains uncertain
|
||||
|
||||
### 5. Record
|
||||
- Document findings with sources
|
||||
- Update memory if findings are durable
|
||||
- Share with relevant agents
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Accepting the first source without cross-referencing
|
||||
- Confusing opinions with facts
|
||||
- Not citing sources
|
||||
- Going too deep (research rabbit holes)
|
||||
- Not stopping when the question is answered
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Question answered with evidence
|
||||
- Sources cited
|
||||
- Confidence level stated
|
||||
- Uncertainties documented
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: security-review
|
||||
description: Security review methodology — identifying and assessing security implications of changes
|
||||
version: "1.0"
|
||||
owner: Reviewer
|
||||
prerequisites: implementation completed, scope understood
|
||||
---
|
||||
|
||||
# Security Review
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- Changes involving authentication, authorization, or access control
|
||||
- Changes to data handling, storage, or transmission
|
||||
- Changes to external API interactions
|
||||
- Changes to shell execution or system commands
|
||||
- Any change where security implications are uncertain
|
||||
|
||||
## Core methodology
|
||||
|
||||
```text
|
||||
IDENTIFY CHANGE → ASSESS ATTACK SURFACE → CHECK VALIDATION → CHECK AUTH → CHECK DATA → CHECK DEPS → VERDICT
|
||||
```
|
||||
|
||||
## Security review checklist
|
||||
|
||||
### Input validation
|
||||
- [ ] All external inputs validated and sanitized
|
||||
- [ ] No SQL injection, command injection, or path traversal
|
||||
- [ ] File uploads validated (type, size, content)
|
||||
|
||||
### Authentication & authorization
|
||||
- [ ] Authentication checks are present and correct
|
||||
- [ ] Authorization checks enforce least privilege
|
||||
- [ ] No bypasses or backdoors
|
||||
|
||||
### Data protection
|
||||
- [ ] Sensitive data is not logged or exposed
|
||||
- [ ] Secrets are not hardcoded
|
||||
- [ ] Data at rest and in transit is protected appropriately
|
||||
|
||||
### Error handling
|
||||
- [ ] Errors do not leak sensitive information
|
||||
- [ ] Stack traces are not exposed to users
|
||||
- [ ] Graceful degradation on security failures
|
||||
|
||||
### Dependencies
|
||||
- [ ] Dependencies are from trusted sources
|
||||
- [ ] No known vulnerabilities in dependencies
|
||||
- [ ] Dependency versions are pinned
|
||||
|
||||
### Shell & system
|
||||
- [ ] Shell commands use safe execution patterns
|
||||
- [ ] File permissions are appropriate
|
||||
- [ ] Temporary files are handled securely
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Assuming "it's internal" means "it's safe"
|
||||
- Trusting user input without validation
|
||||
- Hardcoding credentials (even "temporary" ones)
|
||||
- Logging sensitive data
|
||||
- Not considering the attack surface
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- All checklist items addressed
|
||||
- Findings categorized: CRITICAL / HIGH / MEDIUM / LOW / INFO
|
||||
- Risk assessment for each finding
|
||||
- Remediation plan for non-INFO findings
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: systematic-debugging
|
||||
description: Systematic debugging methodology — hypothesis-driven root cause investigation
|
||||
version: "1.0"
|
||||
owner: Detective
|
||||
prerequisites: symptom observed, reproducible failure available
|
||||
---
|
||||
|
||||
# Systematic Debugging
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- A test fails, a feature breaks, or behavior diverges from expectation
|
||||
- The root cause is not immediately obvious
|
||||
- Multiple possible causes exist
|
||||
|
||||
## Core methodology
|
||||
|
||||
```text
|
||||
SYMPTOM → OBSERVE → HYPOTHESIZE → TEST → TRACE → ELIMINATE → ROOT CAUSE
|
||||
```
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Reproduce the symptom
|
||||
- Confirm you can trigger the failure reliably
|
||||
- Record the exact command, input, and output
|
||||
- Note the environment (OS, versions, state)
|
||||
|
||||
### 2. Observe the evidence
|
||||
- Read error messages carefully (every word matters)
|
||||
- Check logs, stack traces, and output
|
||||
- Note what changed since the last working state
|
||||
|
||||
### 3. Form hypotheses
|
||||
- List possible causes (aim for 3-5)
|
||||
- Rank by likelihood based on evidence
|
||||
- For each hypothesis: what would be true if this were the cause?
|
||||
|
||||
### 4. Test hypotheses
|
||||
- Design the cheapest test for the most likely hypothesis
|
||||
- Use binary elimination: each test should rule out at least one hypothesis
|
||||
- Record what you actually observed vs. what you expected
|
||||
|
||||
### 5. Trace the failure
|
||||
- Follow the execution path from symptom to cause
|
||||
- Add strategic print/log statements if needed
|
||||
- Narrow down: which component, which function, which line?
|
||||
|
||||
### 6. Eliminate alternatives
|
||||
- Explicitly state why other hypotheses are ruled out
|
||||
- Document the evidence for each elimination
|
||||
|
||||
### 7. Establish root cause
|
||||
- State the root cause with confidence level (high/medium/low)
|
||||
- Provide supporting evidence (file:line, command output)
|
||||
- Identify what conditions make this cause trigger
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Fixing the symptom without understanding the cause
|
||||
- Jumping to the most obvious hypothesis without testing it
|
||||
- Changing multiple things at once (can't isolate what fixed it)
|
||||
- Accepting "it works now" without understanding why
|
||||
- Not recording what was eliminated
|
||||
|
||||
## Evidence requirements
|
||||
|
||||
- Reproduction steps
|
||||
- Hypotheses with evidence for/against
|
||||
- Root cause statement with confidence level
|
||||
- Eliminated alternatives with reasoning
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Root cause identified with evidence
|
||||
- Alternative hypotheses eliminated with reasoning
|
||||
- Confidence level stated (high/medium/low)
|
||||
- Report handed off to appropriate agent for resolution
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
name: tdd
|
||||
description: Test-Driven Development methodology — write tests first, implement to pass, refactor
|
||||
version: "1.0"
|
||||
owner: Builder + Tester
|
||||
prerequisites: test framework identified, build system working
|
||||
---
|
||||
|
||||
# Test-Driven Development
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- Implementing new functionality where correctness can be verified
|
||||
- Bug fixes where a regression test should exist
|
||||
- Any change where the expected behavior is well-defined
|
||||
|
||||
## Core methodology
|
||||
|
||||
```text
|
||||
RED → write a failing test that captures the requirement
|
||||
GREEN → implement the minimum code to make the test pass
|
||||
REFACTOR → improve the code while keeping all tests green
|
||||
```
|
||||
|
||||
## Step-by-step procedure
|
||||
|
||||
### 1. Understand the requirement
|
||||
- What behavior is expected?
|
||||
- What inputs produce what outputs?
|
||||
- What edge cases exist?
|
||||
- What error conditions should be handled?
|
||||
|
||||
### 2. Write the test (RED)
|
||||
- Write the smallest test that captures one aspect of the requirement
|
||||
- Verify the test fails for the right reason (not a syntax error)
|
||||
- Run the test to confirm it fails
|
||||
|
||||
### 3. Implement (GREEN)
|
||||
- Write the minimum code to make the test pass
|
||||
- Do not add behavior not captured by a test
|
||||
- Run the test to confirm it passes
|
||||
|
||||
### 4. Verify (REFACTOR)
|
||||
- Run the full test suite (not just the new test)
|
||||
- Refactor if needed: extract methods, rename for clarity, remove duplication
|
||||
- Verify tests still pass after each refactor step
|
||||
|
||||
### 5. Repeat
|
||||
- Return to step 1 for the next aspect of the requirement
|
||||
- Stop when all aspects are covered and tests pass
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Writing tests after implementation (loses the design benefit)
|
||||
- Writing too many tests at once (harder to isolate failures)
|
||||
- Testing implementation details instead of behavior
|
||||
- Skipping the refactor step (technical debt accumulates)
|
||||
- Not running the full suite after changes
|
||||
|
||||
## Evidence requirements
|
||||
|
||||
- Test file with the new test(s)
|
||||
- Test output showing RED → GREEN progression
|
||||
- Full suite passing after completion
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- All new tests pass
|
||||
- Full existing suite passes
|
||||
- Tests capture the behavior, not the implementation
|
||||
- Each test is independently runnable
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: test-analysis
|
||||
description: Test analysis — evaluating test quality, coverage gaps, and test strategy
|
||||
version: "1.0"
|
||||
owner: Tester
|
||||
prerequisites: test suite exists
|
||||
---
|
||||
|
||||
# Test Analysis
|
||||
|
||||
## When to use this skill
|
||||
|
||||
- Evaluating test quality before accepting changes
|
||||
- Identifying coverage gaps
|
||||
- Designing test strategy for new features
|
||||
|
||||
## Core methodology
|
||||
|
||||
```text
|
||||
EXAMINE TESTS → ASSESS COVERAGE → EVALUATE QUALITY → IDENTIFY GAPS → PRIORITIZE → RECOMMEND
|
||||
```
|
||||
|
||||
## Analysis dimensions
|
||||
|
||||
### Coverage
|
||||
- What code paths are exercised?
|
||||
- What branches are tested?
|
||||
- What error conditions are covered?
|
||||
|
||||
### Quality
|
||||
- Do tests verify behavior (not implementation)?
|
||||
- Are tests independent (no ordering dependencies)?
|
||||
- Are tests deterministic (no flakiness)?
|
||||
- Are assertions meaningful (not just "no crash")?
|
||||
|
||||
### Completeness
|
||||
- Are edge cases tested?
|
||||
- Are boundary conditions covered?
|
||||
- Are error paths tested?
|
||||
- Are integration points verified?
|
||||
|
||||
### Maintainability
|
||||
- Are tests readable?
|
||||
- Are tests well-organized?
|
||||
- Are tests fast enough for the feedback loop?
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
- Testing implementation details (breaks on refactor)
|
||||
- Writing tests that always pass (no real verification)
|
||||
- Missing the failure path (happy path only)
|
||||
- Slow tests that discourage running them
|
||||
- Flaky tests that erode confidence
|
||||
|
||||
## Exit criteria
|
||||
|
||||
- Coverage gaps identified with severity
|
||||
- Test quality assessment complete
|
||||
- Recommendations for improvement prioritized
|
||||
Reference in New Issue
Block a user