From 0b6e788aeb99bbb9c04fcd4823192c07b2631695 Mon Sep 17 00:00:00 2001 From: Seth Ford Date: Sun, 1 Mar 2026 13:00:40 -0500 Subject: [PATCH 1/2] docs: auto-sync stale documentation sections --- .claude/CLAUDE.md | 4 +-- scripts/skills/api-design.md | 33 ++++++++++++++++++++++ scripts/skills/brainstorming.md | 30 ++++++++++++++++++++ scripts/skills/data-pipeline.md | 33 ++++++++++++++++++++++ scripts/skills/documentation.md | 28 +++++++++++++++++++ scripts/skills/frontend-design.md | 34 +++++++++++++++++++++++ scripts/skills/performance.md | 37 +++++++++++++++++++++++++ scripts/skills/product-thinking.md | 33 ++++++++++++++++++++++ scripts/skills/security-audit.md | 38 ++++++++++++++++++++++++++ scripts/skills/systematic-debugging.md | 29 ++++++++++++++++++++ scripts/skills/testing-strategy.md | 37 +++++++++++++++++++++++++ scripts/skills/two-stage-review.md | 36 ++++++++++++++++++++++++ 12 files changed, 370 insertions(+), 2 deletions(-) create mode 100644 scripts/skills/api-design.md create mode 100644 scripts/skills/brainstorming.md create mode 100644 scripts/skills/data-pipeline.md create mode 100644 scripts/skills/documentation.md create mode 100644 scripts/skills/frontend-design.md create mode 100644 scripts/skills/performance.md create mode 100644 scripts/skills/product-thinking.md create mode 100644 scripts/skills/security-audit.md create mode 100644 scripts/skills/systematic-debugging.md create mode 100644 scripts/skills/testing-strategy.md create mode 100644 scripts/skills/two-stage-review.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 46f77fc16..6735616dc 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -526,7 +526,7 @@ All scripts are bash (except the dashboard server in TypeScript). Grouped by lay | `scripts/sw-incident.sh` | 873 | Autonomous Incident Detection & Response | | `scripts/sw-init.sh` | 867 | Complete setup for Shipwright + Shipwright | | `scripts/sw-instrument.sh` | 691 | Pipeline Instrumentation & Feedback Loops | -| `scripts/sw-intelligence.sh` | 1523 | AI-Powered Analysis & Decision Engine | +| `scripts/sw-intelligence.sh` | 1547 | AI-Powered Analysis & Decision Engine | | `scripts/sw-jira.sh` | 628 | Jira ↔ GitHub Bidirectional Sync | | `scripts/sw-launchd.sh` | 703 | Process supervision (macOS + Linux) | | `scripts/sw-linear.sh` | 643 | Linear ↔ GitHub Bidirectional Sync | @@ -540,7 +540,7 @@ All scripts are bash (except the dashboard server in TypeScript). Grouped by lay | `scripts/sw-patrol-meta.sh` | 445 | Shipwright Self-Improvement Patrol | | `scripts/sw-pipeline-composer.sh` | 444 | Dynamic Pipeline Composition | | `scripts/sw-pipeline-vitals.sh` | 1076 | Pipeline Vitals Engine | -| `scripts/sw-pipeline.sh` | 2883 | Autonomous Feature Delivery (Idea → Production) | +| `scripts/sw-pipeline.sh` | 2944 | Autonomous Feature Delivery (Idea → Production) | | `scripts/sw-pm.sh` | 748 | Autonomous PM Agent for Team Orchestration | | `scripts/sw-pr-lifecycle.sh` | 688 | Autonomous PR Management | | `scripts/sw-predictive.sh` | 834 | Predictive & Proactive Intelligence | diff --git a/scripts/skills/api-design.md b/scripts/skills/api-design.md new file mode 100644 index 000000000..b99c2ad14 --- /dev/null +++ b/scripts/skills/api-design.md @@ -0,0 +1,33 @@ +## API Design Expertise + +Apply these API design patterns: + +### RESTful Conventions +- Use nouns for resources, HTTP verbs for actions (GET /users, POST /users, DELETE /users/:id) +- Return appropriate status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 422 Unprocessable +- Use consistent error response format: `{ "error": { "code": "...", "message": "..." } }` +- Version APIs when breaking changes are needed (/v1/users, /v2/users) + +### Request/Response Design +- Accept and return JSON (Content-Type: application/json) +- Use camelCase for JSON field names +- Include pagination for list endpoints (limit, offset or cursor) +- Support filtering and sorting via query parameters + +### Input Validation +- Validate ALL input at the API boundary — never trust client data +- Return specific validation errors with field names +- Sanitize strings against injection (SQL, XSS, command injection) +- Set reasonable size limits on request bodies + +### Error Handling +- Never expose stack traces or internal errors to clients +- Log full error details server-side +- Use consistent error codes that clients can programmatically handle +- Include request-id in responses for debugging + +### Authentication & Authorization +- Verify auth on EVERY endpoint (don't rely on frontend-only checks) +- Use principle of least privilege for authorization +- Validate tokens/sessions on each request +- Rate limit sensitive endpoints (login, password reset) diff --git a/scripts/skills/brainstorming.md b/scripts/skills/brainstorming.md new file mode 100644 index 000000000..8fdbc0d9f --- /dev/null +++ b/scripts/skills/brainstorming.md @@ -0,0 +1,30 @@ +## Brainstorming: Socratic Design Refinement + +Before writing the implementation plan, challenge your assumptions with these questions: + +### Requirements Clarity +- What is the **minimum viable change** that satisfies this issue? +- Are there implicit requirements not stated in the issue? +- What are the acceptance criteria? If none are stated, define them. + +### Design Alternatives +- What are at least 2 different approaches to solve this? +- What are the trade-offs of each? (complexity, performance, maintainability) +- Which approach minimizes the blast radius of changes? + +### Risk Assessment +- What could go wrong with the chosen approach? +- What existing functionality could break? +- Are there edge cases not covered by the issue description? + +### Dependency Analysis +- What existing code does this depend on? +- What other code depends on what you're changing? +- Are there any circular dependency risks? + +### Simplicity Check +- Can this be solved with fewer files changed? +- Is there existing infrastructure you can reuse? +- Would a simpler approach work for 90% of cases? + +Document your reasoning in the plan. Show the alternatives you considered and why you chose this approach. diff --git a/scripts/skills/data-pipeline.md b/scripts/skills/data-pipeline.md new file mode 100644 index 000000000..1abf679eb --- /dev/null +++ b/scripts/skills/data-pipeline.md @@ -0,0 +1,33 @@ +## Data Pipeline Expertise + +Apply these data engineering patterns: + +### Schema Design +- Define schemas explicitly — never rely on implicit structure +- Use migrations for all schema changes (never manual ALTER TABLE) +- Add indexes for frequently queried columns +- Consider denormalization for read-heavy paths + +### Data Integrity +- Use transactions for multi-step operations +- Implement idempotency keys for operations that could be retried +- Validate data at ingestion — reject bad data early +- Use constraints (NOT NULL, UNIQUE, FOREIGN KEY) in the database layer + +### Query Patterns +- Avoid N+1 queries — use JOINs or batch loading +- Use EXPLAIN to verify query plans for complex queries +- Paginate large result sets — never SELECT * without LIMIT +- Use parameterized queries — never string concatenation for SQL + +### Migration Safety +- Migrations must be reversible (include rollback steps) +- Test migrations on a copy of production data +- Add new columns as nullable, then backfill, then add NOT NULL +- Never drop columns in the same deploy as code changes + +### Backpressure & Resilience +- Implement circuit breakers for external data sources +- Use dead letter queues for failed processing +- Set timeouts on all external calls +- Monitor queue depths and processing latency diff --git a/scripts/skills/documentation.md b/scripts/skills/documentation.md new file mode 100644 index 000000000..9216d13da --- /dev/null +++ b/scripts/skills/documentation.md @@ -0,0 +1,28 @@ +## Documentation Expertise + +For documentation-focused issues, apply a lightweight approach: + +### Scope +- Focus on accuracy over comprehensiveness +- Update only what's actually changed or incorrect +- Remove outdated information rather than marking it deprecated +- Keep examples current and runnable + +### Writing Style +- Use active voice and present tense +- Lead with the most important information +- Use code examples for anything technical +- Keep paragraphs short — 2-3 sentences max + +### Structure +- Start with a one-line summary of what this documents +- Include prerequisites and setup if applicable +- Provide a quick start / most common usage first +- Put advanced topics and edge cases later + +### Skip Heavy Stages +This is a documentation change. The following pipeline stages can be simplified: +- **Design stage**: Skip — documentation doesn't need architecture design +- **Build stage**: Focus on file edits only, no compilation needed +- **Test stage**: Verify links work and examples are syntactically correct +- **Review stage**: Focus on accuracy and clarity, not code patterns diff --git a/scripts/skills/frontend-design.md b/scripts/skills/frontend-design.md new file mode 100644 index 000000000..d437284dd --- /dev/null +++ b/scripts/skills/frontend-design.md @@ -0,0 +1,34 @@ +## Frontend Design Expertise + +Apply these frontend patterns to your implementation: + +### Accessibility (Required) +- All interactive elements must have keyboard support +- Use semantic HTML elements (button, nav, main, article) +- Include aria-labels for non-text interactive elements +- Ensure color contrast meets WCAG AA (4.5:1 for text) +- Test with screen reader mental model: does the DOM order make sense? + +### Responsive Design +- Mobile-first: start with mobile layout, enhance for larger screens +- Use relative units (rem, %, vh/vw) instead of fixed pixels +- Test breakpoints: 320px, 768px, 1024px, 1440px +- Touch targets: minimum 44x44px + +### Component Patterns +- Keep components focused — one responsibility per component +- Lift state up only when siblings need to share it +- Use composition over inheritance +- Handle loading, error, and empty states for every data-dependent component + +### Performance +- Lazy-load below-the-fold content +- Optimize images (appropriate format, size, lazy loading) +- Minimize re-renders — check dependency arrays in effects +- Avoid layout thrashing — batch DOM reads and writes + +### User Experience +- Provide immediate feedback for user actions +- Show loading indicators for operations > 300ms +- Use optimistic updates where safe +- Preserve user input on errors — never clear forms on failed submit diff --git a/scripts/skills/performance.md b/scripts/skills/performance.md new file mode 100644 index 000000000..f6a6f593f --- /dev/null +++ b/scripts/skills/performance.md @@ -0,0 +1,37 @@ +## Performance Expertise + +Apply these optimization patterns: + +### Profiling First +- Measure before optimizing — identify the actual bottleneck +- Use profiling tools appropriate to the language/runtime +- Focus on the critical path — optimize what users experience + +### Caching Strategy +- Cache expensive computations and repeated queries +- Set appropriate TTLs — stale data vs freshness trade-off +- Invalidate caches on write operations +- Use cache layers: in-memory (L1) → distributed (L2) → database (L3) + +### Database Performance +- Add indexes for frequently queried columns (check EXPLAIN plans) +- Avoid N+1 queries — use batch loading or JOINs +- Use connection pooling +- Consider read replicas for read-heavy workloads + +### Algorithm Complexity +- Prefer O(n log n) over O(n²) for sorting/searching +- Use appropriate data structures (hash maps for lookups, trees for ranges) +- Avoid unnecessary allocations in hot paths +- Pre-compute values that are used repeatedly + +### Network Optimization +- Minimize round trips — batch API calls where possible +- Use compression for large payloads +- Implement pagination — never return unbounded result sets +- Use CDNs for static assets + +### Benchmarking +- Include before/after benchmarks for performance changes +- Test with realistic data volumes (not just unit test fixtures) +- Measure p50, p95, p99 latencies — not just averages diff --git a/scripts/skills/product-thinking.md b/scripts/skills/product-thinking.md new file mode 100644 index 000000000..667dc24eb --- /dev/null +++ b/scripts/skills/product-thinking.md @@ -0,0 +1,33 @@ +## Product Thinking Expertise + +Consider the user perspective in your implementation: + +### User Stories +- Who is the user for this feature? +- What problem does this solve for them? +- What is their workflow before and after this change? +- Define acceptance criteria from the user's perspective + +### User Experience +- What is the simplest interaction that solves the problem? +- How does the user discover this feature? +- What happens when things go wrong? (error states, recovery) +- Is the feature accessible to users with disabilities? + +### Edge Cases from User Perspective +- What if the user has no data yet? (empty state) +- What if the user has too much data? (pagination, filtering) +- What if the user makes a mistake? (undo, confirmation) +- What if the user is on a slow connection? (loading states) + +### Progressive Disclosure +- Show the most important information first +- Hide complexity behind progressive interactions +- Don't overwhelm with options — provide sensible defaults +- Use contextual help instead of documentation + +### Feedback & Communication +- Confirm successful actions immediately +- Explain errors in plain language — not error codes +- Show progress for long-running operations +- Preserve user context across navigation diff --git a/scripts/skills/security-audit.md b/scripts/skills/security-audit.md new file mode 100644 index 000000000..61ce227dd --- /dev/null +++ b/scripts/skills/security-audit.md @@ -0,0 +1,38 @@ +## Security Audit Expertise + +Apply OWASP Top 10 and security best practices: + +### Injection Prevention +- Use parameterized queries for ALL database access +- Sanitize user input before rendering in HTML/templates +- Validate and sanitize file paths — prevent directory traversal +- Never execute user-supplied strings as code or commands + +### Authentication +- Hash passwords with bcrypt/argon2 (never MD5/SHA1) +- Implement account lockout after failed attempts +- Use secure session management (HttpOnly, Secure, SameSite cookies) +- Require re-authentication for sensitive operations + +### Authorization +- Check permissions server-side on EVERY request +- Use deny-by-default — explicitly grant access +- Verify resource ownership (user can only access their own data) +- Log authorization failures for monitoring + +### Data Protection +- Never log sensitive data (passwords, tokens, PII) +- Encrypt sensitive data at rest +- Use HTTPS for all communications +- Set appropriate CORS headers — never use wildcard in production + +### Secrets Management +- Never hardcode secrets in source code +- Use environment variables or secret managers +- Rotate secrets regularly +- Check for accidentally committed secrets (API keys, passwords, tokens) + +### Dependency Security +- Check for known vulnerabilities in dependencies +- Pin dependency versions to prevent supply chain attacks +- Review new dependencies before adding them diff --git a/scripts/skills/systematic-debugging.md b/scripts/skills/systematic-debugging.md new file mode 100644 index 000000000..83d362ce3 --- /dev/null +++ b/scripts/skills/systematic-debugging.md @@ -0,0 +1,29 @@ +## Systematic Debugging: Root Cause Analysis + +A previous attempt at this stage FAILED. Do NOT blindly retry the same approach. Follow this 4-phase investigation: + +### Phase 1: Evidence Collection +- Read the error output from the previous attempt carefully +- Identify the EXACT line/file where the failure occurred +- Check if the error is a symptom or the root cause +- Look for patterns: is this a known error type? + +### Phase 2: Hypothesis Formation +- List 3 possible root causes for this failure +- For each hypothesis, identify what evidence would confirm or deny it +- Rank hypotheses by likelihood + +### Phase 3: Root Cause Verification +- Test the most likely hypothesis first +- Read the relevant source code — don't guess +- Check if previous artifacts (plan.md, design.md) are correct or flawed +- If the plan was correct but execution failed, focus on execution +- If the plan was flawed, document what was wrong + +### Phase 4: Targeted Fix +- Fix the ROOT CAUSE, not the symptom +- If the previous approach was fundamentally wrong, choose a different approach +- If it was a minor error, make the minimal fix +- Document what went wrong and why the new approach is better + +IMPORTANT: If you find existing artifacts from a successful previous stage, USE them — don't regenerate from scratch. diff --git a/scripts/skills/testing-strategy.md b/scripts/skills/testing-strategy.md new file mode 100644 index 000000000..5d730062d --- /dev/null +++ b/scripts/skills/testing-strategy.md @@ -0,0 +1,37 @@ +## Testing Strategy Expertise + +Apply these testing patterns: + +### Test Pyramid +- **Unit tests** (70%): Test individual functions/methods in isolation +- **Integration tests** (20%): Test component interactions and boundaries +- **E2E tests** (10%): Test critical user flows end-to-end + +### What to Test +- Happy path: the expected successful flow +- Error cases: what happens when things go wrong? +- Edge cases: empty inputs, maximum values, concurrent access +- Boundary conditions: off-by-one, empty collections, null/undefined + +### Test Quality +- Each test should verify ONE behavior +- Test names should describe the expected behavior, not the implementation +- Tests should be independent — no shared mutable state between tests +- Tests should be deterministic — same result every run + +### Coverage Strategy +- Aim for meaningful coverage, not 100% line coverage +- Focus coverage on business logic and error handling +- Don't test framework code or simple getters/setters +- Cover the branches, not just the lines + +### Mocking Guidelines +- Mock external dependencies (APIs, databases, file system) +- Don't mock the code under test +- Use realistic test data — edge cases reveal bugs +- Verify mock interactions when the side effect IS the behavior + +### Regression Testing +- Write a failing test FIRST that reproduces the bug +- Then fix the bug and verify the test passes +- Keep regression tests — they prevent the bug from recurring diff --git a/scripts/skills/two-stage-review.md b/scripts/skills/two-stage-review.md new file mode 100644 index 000000000..9bc921454 --- /dev/null +++ b/scripts/skills/two-stage-review.md @@ -0,0 +1,36 @@ +## Two-Stage Code Review + +This review runs in two passes. Complete Pass 1 fully before starting Pass 2. + +### Pass 1: Spec Compliance + +Compare the implementation against the plan and issue requirements: + +1. **Task Checklist**: Does the code implement every task from plan.md? +2. **Files Modified**: Were all planned files actually modified? +3. **Requirements Coverage**: Does the implementation satisfy every requirement from the issue? +4. **Missing Features**: Is anything from the plan NOT implemented? +5. **Scope Creep**: Was anything added that WASN'T in the plan? + +For each gap found: +- **[SPEC-GAP]** description — what was planned vs what was implemented + +If all requirements are met, write: "Spec compliance: PASS — all planned tasks implemented." + +--- + +### Pass 2: Code Quality + +Now review the code for engineering quality: + +1. **Logic bugs** — incorrect conditions, off-by-one errors, null handling +2. **Security** — injection, XSS, auth bypass, secret exposure +3. **Error handling** — missing catch blocks, silent failures, unclear error messages +4. **Performance** — unnecessary loops, missing indexes, N+1 queries +5. **Naming and clarity** — confusing names, missing context, magic numbers +6. **Test coverage** — are new code paths tested? Edge cases covered? + +For each issue found, use format: +- **[SEVERITY]** file:line — description + +Severity: Critical, Bug, Security, Warning, Suggestion From e8b5b3a491aaa572259069c187a544ff5cc79870 Mon Sep 17 00:00:00 2001 From: Seth Ford Date: Sun, 1 Mar 2026 13:33:43 -0500 Subject: [PATCH 2/2] docs: fix stale core-scripts line counts in CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update AUTO:core-scripts section with correct line counts: - sw-intelligence.sh: 1547 → 1523 - sw-pipeline.sh: 2944 → 2883 Fixes #190 Co-Authored-By: Claude Opus 4.6 --- .claude/CLAUDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 6735616dc..46f77fc16 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -526,7 +526,7 @@ All scripts are bash (except the dashboard server in TypeScript). Grouped by lay | `scripts/sw-incident.sh` | 873 | Autonomous Incident Detection & Response | | `scripts/sw-init.sh` | 867 | Complete setup for Shipwright + Shipwright | | `scripts/sw-instrument.sh` | 691 | Pipeline Instrumentation & Feedback Loops | -| `scripts/sw-intelligence.sh` | 1547 | AI-Powered Analysis & Decision Engine | +| `scripts/sw-intelligence.sh` | 1523 | AI-Powered Analysis & Decision Engine | | `scripts/sw-jira.sh` | 628 | Jira ↔ GitHub Bidirectional Sync | | `scripts/sw-launchd.sh` | 703 | Process supervision (macOS + Linux) | | `scripts/sw-linear.sh` | 643 | Linear ↔ GitHub Bidirectional Sync | @@ -540,7 +540,7 @@ All scripts are bash (except the dashboard server in TypeScript). Grouped by lay | `scripts/sw-patrol-meta.sh` | 445 | Shipwright Self-Improvement Patrol | | `scripts/sw-pipeline-composer.sh` | 444 | Dynamic Pipeline Composition | | `scripts/sw-pipeline-vitals.sh` | 1076 | Pipeline Vitals Engine | -| `scripts/sw-pipeline.sh` | 2944 | Autonomous Feature Delivery (Idea → Production) | +| `scripts/sw-pipeline.sh` | 2883 | Autonomous Feature Delivery (Idea → Production) | | `scripts/sw-pm.sh` | 748 | Autonomous PM Agent for Team Orchestration | | `scripts/sw-pr-lifecycle.sh` | 688 | Autonomous PR Management | | `scripts/sw-predictive.sh` | 834 | Predictive & Proactive Intelligence |