@mclawnet/agent 0.5.9 → 0.6.2

package/skills/chart-visualization/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: chart-visualization
+description: Design and generate data visualizations including charts, graphs, and diagrams. Use when creating bar charts, line graphs, pie charts, scatter plots, heatmaps, or any data-driven visual representation.
+disable-model-invocation: true
+---
+
+# Chart Visualization
+
+Design effective data visualizations by selecting the right chart type for your data, applying best practices for clarity and accuracy, and generating production-quality charts.
+
+## Overview
+
+This skill guides the entire chart creation process: understanding your data's story, choosing the appropriate visualization type, designing for clarity, and implementing with popular charting libraries. The goal is always a chart that communicates insight at a glance.
+
+## When to Use
+
+- Creating charts or graphs from data
+- Choosing the right visualization type for a dataset
+- Designing dashboards with multiple visual components
+- Converting raw numbers into visual stories for presentations or reports
+- Generating interactive or static data visualizations
+
+## When NOT to Use
+
+- **Data analysis or computation** — use the `data-analysis` skill for processing data before visualization
+- **Infographic design** — for non-data-driven visual design, use general design skills
+- **Diagram creation** (flowcharts, architecture diagrams) — those are structural, not data-driven
+
+## Chart Type Selection Guide
+
+### By Data Relationship
+
+| What You Want to Show | Chart Type | When to Use |
+|---|---|---|
+| Comparison across categories | Bar chart (vertical) | ≤12 categories, emphasizing magnitude |
+| Comparison with long labels | Bar chart (horizontal) | Long category names, ranking |
+| Change over time | Line chart | Continuous time series, trends |
+| Part of a whole | Pie / Donut chart | ≤6 slices, percentages that sum to 100% |
+| Part of a whole (many categories) | Stacked bar chart | >6 categories, comparison across groups |
+| Distribution | Histogram | Continuous variable frequency |
+| Correlation | Scatter plot | Two continuous variables, pattern detection |
+| Density / frequency | Heatmap | Two categorical axes, many data points |
+| Range / uncertainty | Error bar / Box plot | Statistical spread, confidence intervals |
+| Geographic data | Choropleth / Bubble map | Location-based values |
+| Hierarchy | Treemap / Sunburst | Nested categories with values |
+| Flow / process | Sankey diagram | Quantities flowing between stages |
+| Progress toward goal | Gauge / Progress bar | Single value against target |
+
+### Decision Flowchart
+
+```
+What is the data about?
+├── Comparing values → How many categories?
+│   ├── ≤5 → Grouped bar chart
+│   ├── 6-12 → Horizontal bar chart
+│   └── >12 → Consider filtering or small multiples
+├── Showing change over time → How many series?
+│   ├── 1-3 → Line chart
+│   ├── 4-7 → Line chart with legend or small multiples
+│   └── >7 → Heatmap or highlight key series
+├── Showing proportions → How many parts?
+│   ├── ≤6 → Pie or donut chart
+│   └── >6 → Stacked bar or treemap
+├── Showing relationships → Scatter plot or bubble chart
+├── Showing distribution → Histogram or box plot
+└── Showing geographic patterns → Map visualization
+```
+
+## Design Principles
+
+### Clarity First
+
+1. **Title**: Always include a descriptive title that tells the story ("Sales grew 40% in Q3" > "Q3 Sales Data")
+2. **Axes**: Label both axes with units. Use human-readable scales (1K, 1M, not 1000, 1000000)
+3. **Legend**: Place inside the chart area when possible. Order matches visual order
+4. **Color**: Use a consistent palette. Maximum 7 distinct colors before confusion sets in
+5. **Gridlines**: Light, subtle. Remove when not needed for reading values
+
+### Honesty Rules
+
+- **Start Y-axis at zero** for bar charts (truncated axes exaggerate differences)
+- **Use consistent intervals** on time axes (don't compress gaps)
+- **Avoid 3D effects** — they distort perception of values
+- **Avoid dual Y-axes** when possible — they confuse more than clarify
+- **Show data density honestly** — don't cherry-pick ranges that support a narrative
+
+### Responsive Design
+
+- Design for the smallest expected display size first
+- Use relative sizing (%, vw/vh) not fixed pixels for web
+- Reduce label density on mobile — rotate or abbreviate
+- Consider small multiples over complex combined charts on small screens
+
+## Implementation Patterns
+
+### With Chart.js (JavaScript)
+
+```javascript
+const chart = new Chart(ctx, {
+  type: 'bar',
+  data: {
+    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
+    datasets: [{
+      label: 'Revenue ($K)',
+      data: [120, 150, 180, 210],
+      backgroundColor: '#4F46E5'
+    }]
+  },
+  options: {
+    responsive: true,
+    plugins: { title: { display: true, text: 'Monthly Revenue 2024' } },
+    scales: { y: { beginAtZero: true } }
+  }
+});
+```
+
+### With Python (Matplotlib / Seaborn)
+
+```python
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+fig, ax = plt.subplots(figsize=(10, 6))
+sns.barplot(data=df, x='month', y='revenue', ax=ax)
+ax.set_title('Monthly Revenue 2024')
+ax.set_ylabel('Revenue ($K)')
+plt.tight_layout()
+plt.savefig('revenue.png', dpi=150)
+```
+
+### With D3.js (Custom SVG)
+
+```javascript
+const svg = d3.select('#chart')
+  .append('svg')
+  .attr('viewBox', `0 0 ${width} ${height}`);
+
+svg.selectAll('rect')
+  .data(data)
+  .join('rect')
+  .attr('x', d => xScale(d.label))
+  .attr('y', d => yScale(d.value))
+  .attr('width', xScale.bandwidth())
+  .attr('height', d => height - margin.bottom - yScale(d.value))
+  .attr('fill', '#4F46E5');
+```
+
+## Color Palettes
+
+### Sequential (single variable, low-to-high)
+- Blues: `#EFF6FF → #1D4ED8` (light background to dark emphasis)
+- Greens: `#F0FDF4 → #15803D`
+
+### Diverging (positive/negative, above/below center)
+- Red-Blue: `#DC2626 → #F5F5F5 → #2563EB`
+- Orange-Purple: `#EA580C → #F5F5F5 → #7C3AED`
+
+### Categorical (distinct groups)
+- Default 7: `#4F46E5, #059669, #D97706, #DC2626, #7C3AED, #0891B2, #DB2777`
+- Accessible: meets WCAG contrast for both light and dark backgrounds
+
+### Colorblind-Safe Rules
+- Never use red/green alone to distinguish categories
+- Add patterns (hatching, dots) as a secondary differentiator
+- Use colorblind simulation tools to verify
+
+## Common Anti-Patterns
+
+### Pie Chart Overuse
+**Problem**: More than 6 slices, or slices of similar size, make pie charts unreadable.
+**Fix**: Use a horizontal bar chart sorted by value.
+
+### Spaghetti Line Charts
+**Problem**: 10+ overlapping lines create visual noise.
+**Fix**: Highlight 2-3 key series, gray out the rest. Or use small multiples.
+
+### Missing Context
+**Problem**: A chart without comparison points ("Is 42% good or bad?").
+**Fix**: Add benchmarks, targets, or prior period comparisons.
+
+### Overdecorated Charts
+**Problem**: Gradients, shadows, 3D effects, background images.
+**Fix**: Remove every element that doesn't convey data. Edward Tufte's "data-ink ratio."

package/skills/code-review/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: code-review
+description: Perform systematic, multi-dimensional code reviews on pull requests, diffs, or code snippets. Use when asked to review changes, audit code quality, or assess a PR before merge.
+---
+
+# Code Review
+
+A systematic code review skill that evaluates changes across five dimensions — correctness, security, performance, architecture, and test coverage — using a structured six-step process. Every finding is assigned a severity, confidence level, and concrete fix suggestion.
+
+## Overview
+
+This skill guides a thorough, opinionated code review process. The reviewer acts as a senior engineer whose job is to catch real problems before they reach production, not to rubber-stamp changes.
+
+Core principles:
+- **Be direct.** Every finding takes a clear position: "this is wrong because X" or "this works because Y." Never hedge with "you might want to consider."
+- **Be systematic.** Follow the six-step process in order. Do not skip steps even when the diff looks small.
+- **Be proportional.** Spend review effort proportional to risk. A one-line change to auth logic deserves more scrutiny than a 500-line CSS refactor.
+- **Be constructive.** Every problem identified must include a concrete suggestion for how to fix it.
+- **Be honest about uncertainty.** When you are unsure, say so explicitly with a calibrated confidence level rather than presenting guesses as facts.
+
+The goal is not to find the maximum number of issues. The goal is to find the issues that matter and communicate them clearly.
+
+## When to Use
+
+Activate this skill when:
+- Reviewing a pull request or merge request
+- Reviewing a diff or set of code changes
+- Auditing existing code for quality, security, or correctness
+- Asked to provide feedback on code before it ships
+- Performing a post-incident review of code that caused a bug
+- Comparing two implementations to recommend which is better
+
+## When NOT to Use
+
+Do not use this skill when:
+- **Writing new code from scratch.** Use the architecture or implementation skills instead.
+- **Writing or fixing tests.** Use the testing skill instead.
+- **Debugging a runtime error.** That is a debugging task, not a review task.
+- **Generating boilerplate or scaffolding.** That is code generation, not review.
+- **The user wants unconditional praise.** This skill is designed to find real problems. If the code is good, the review will say so — but it will not inflate quality.
+
+## Review Process
+
+Follow these six steps in order. Complete each step before moving to the next.
+
+### Step 1: Understand Context
+
+Before reading any code, establish what the change is trying to do and why.
+
+- Read the PR title, description, and any linked issues or tickets.
+- Identify the type of change: feature, bugfix, refactor, performance improvement, dependency update, configuration change.
+- Note the scope: which components, services, or layers are affected.
+- Identify the risk profile: does this touch auth, payments, data persistence, public APIs, or other high-risk areas?
+- Form an expectation of what the diff should look like given the stated intent.
+
+If the PR description is missing or unclear, flag this as a finding. Good code review requires good context.
+
+### Step 2: Review Structure
+
+Evaluate the organizational quality of the changes.
+
+- Are new files placed in the correct directories following project conventions?
+- Are files, classes, functions, and variables named clearly and consistently?
+- Is the change appropriately sized? A PR with 50+ changed files may need to be split.
+- Are unrelated changes mixed in (scope creep)? Flag drive-by refactors that complicate review.
+- Do import/dependency changes make sense? Are new dependencies justified?
+- Is dead code being added (commented-out blocks, unused imports, unreachable branches)?
+
+### Step 3: Review Logic
+
+Read the code line-by-line and verify correctness.
+
+- Trace the primary execution path. Does it produce the correct result for typical inputs?
+- Trace error paths. What happens when inputs are null, empty, out of range, or malformed?
+- Check boundary conditions: off-by-one errors, integer overflow, empty collections, concurrent access.
+- Verify state management: are mutations intentional? Is state cleaned up properly?
+- Check control flow: are all branches reachable? Are switch/match statements exhaustive?
+- Verify data transformations: are types correct at each step? Are conversions safe?
+- Check for race conditions in async or concurrent code.
+- Verify that the code actually implements what the PR description claims.
+
+### Step 4: Review Security
+
+Check for vulnerabilities using the OWASP Top 10 as a baseline.
+
+- **Injection**: Are all user inputs validated and sanitized before use in SQL, shell commands, templates, or queries?
+- **Authentication**: Are auth checks present on all protected endpoints? Are tokens validated correctly?
+- **Authorization**: Does the code enforce proper access control? Can user A access user B's data?
+- **Data exposure**: Are secrets, tokens, or PII logged, returned in error messages, or stored in plaintext?
+- **Configuration**: Are default configurations secure? Are debug modes disabled for production?
+- **Dependencies**: Do new dependencies have known vulnerabilities? Are versions pinned?
+- **Cryptography**: Are modern algorithms used? Are random values cryptographically secure where needed?
+
+### Step 5: Review Performance
+
+Identify code that will degrade under load or with large inputs.
+
+- Check algorithmic complexity. Flag O(n²) or worse when O(n) or O(n log n) alternatives exist.
+- Identify N+1 query patterns in database access code.
+- Check for unnecessary memory allocations: large object copies, string concatenation in loops, unbounded buffers.
+- Verify that I/O operations (network, disk, database) are batched where possible.
+- Check caching: is cacheable data being re-fetched? Are cache invalidation strategies correct?
+- Look for blocking operations in async contexts.
+- Verify pagination: are unbounded queries possible? Can a user request unlimited data?
+- Check resource cleanup: are connections, file handles, and streams properly closed?
+
+### Step 6: Review Tests
+
+Evaluate whether the changes are adequately tested.
+
+- Do new features have corresponding test cases?
+- Do bug fixes include a regression test that would have caught the original bug?
+- Are edge cases tested (empty input, null values, error conditions, boundary values)?
+- Are tests actually asserting meaningful behavior, or are they trivially passing?
+- Is mock/stub usage appropriate? Over-mocking can hide real bugs.
+- Do integration tests cover the interaction between changed components?
+- Are test names descriptive enough to serve as documentation?
+- If tests were deleted or modified, is the reason clear and justified?
+
+## Five Review Dimensions
+
+Each dimension receives an independent assessment. A change can score well on security but poorly on architecture.
+
+### 1. Correctness
+
+The code does what it claims to do, handles edge cases, and does not introduce regressions.
+
+Key checklist:
+- Logic matches stated intent in PR description
+- All input types and ranges are handled (including null, undefined, empty, negative, very large)
+- Error handling is exhaustive — no silently swallowed exceptions
+- Return values and types are correct at every call site
+- Side effects are documented or obvious from naming
+- Concurrency and ordering assumptions are explicit and correct
+- Backwards compatibility is maintained unless the breaking change is intentional and documented
+
+### 2. Security
+
+The code does not introduce vulnerabilities that could be exploited.
+
+Key checklist:
+- User input is never trusted: validated, sanitized, or parameterized before use
+- Authentication is checked before any protected operation
+- Authorization is checked at the data layer, not just the UI layer
+- Secrets are not hardcoded, logged, or included in error responses
+- Sensitive data (PII, credentials, tokens) is encrypted at rest and in transit
+- CSRF, XSS, and clickjacking protections are in place for web-facing code
+- Rate limiting and input size limits prevent abuse
+
+### 3. Performance
+
+The code performs acceptably under expected and peak load.
+
+Key checklist:
+- No O(n²) or worse algorithms where better alternatives exist
+- Database queries are indexed and bounded (LIMIT clauses, pagination)
+- No N+1 query patterns
+- Large data sets are streamed, not loaded entirely into memory
+- Expensive computations are cached with correct invalidation
+- Network calls are batched and have timeouts
+- No synchronous blocking in event loops or async contexts
+
+### 4. Architecture
+
+The code fits cleanly into the existing system and does not increase accidental complexity.
+
+Key checklist:
+- Single Responsibility: each function/class/module has one clear purpose
+- Coupling is minimized: changes in module A should not require changes in module B
+- Abstractions are at the right level — not over-engineered, not under-abstracted
+- Public APIs are minimal and well-defined
+- Naming reveals intent: a reader can understand what code does without reading the implementation
+- No God objects, mega-functions, or deeply nested conditionals
+- The change follows established project patterns rather than inventing new ones without justification
+
+### 5. Test Coverage
+
+The changes are protected by tests that will catch future regressions.
+
+Key checklist:
+- Every new public function or method has at least one test
+- Every bug fix has a regression test
+- Happy path, error path, and edge cases are each tested
+- Tests are independent: no ordering dependencies, no shared mutable state
+- Mocks are used for external dependencies, not for the code under test
+- Test assertions are specific (exact values, not just "truthy")
+- Test names describe the scenario and expected outcome
+
+## Confidence Calibration
+
+Every finding must include a confidence level. Miscalibrated confidence — presenting speculation as certainty or burying real bugs in hedging language — is a review quality failure.
+
+### Confidence Levels
+
+- **Certain (95%+)**: You can trace the bug or prove the vulnerability from the code alone. Example: "This SQL query interpolates user input without parameterization. This is a SQL injection vulnerability."
+- **High (80-95%)**: The issue is very likely real but depends on runtime behavior or configuration you cannot fully verify. Example: "This appears to be an N+1 query. If `loadRelated` triggers a separate DB call per item, this will be O(n) queries."
+- **Medium (50-80%)**: The issue is plausible but you are missing context. State what you know and what you would need to confirm. Example: "This cache has no TTL. If the underlying data changes frequently, this could serve stale results."
+- **Low (below 50%)**: You are flagging a potential concern but cannot determine if it is a real problem. Example: "This recursive function does not have an obvious depth limit. It may be fine for expected input sizes, but could stack overflow with deeply nested data."
+
+### Calibration Rules
+
+- If you are Certain, say so directly. Do not soften with "I think" or "it seems."
+- If you are at Medium or Low confidence, explicitly state what additional information would raise your confidence.
+- Never present a Low confidence finding as Critical severity. If you are unsure whether something is a bug, it is a Suggestion, not a Critical.
+- It is better to flag a real issue at Low confidence than to miss it entirely. Include it, but label it honestly.
+
+## Finding Format
+
+Report each finding using this structure:
+
+```
+### [Severity] [Short title]
+
+**Location:** `path/to/file.ts:42-58`
+**Dimension:** Correctness | Security | Performance | Architecture | Test Coverage
+**Confidence:** Certain | High | Medium | Low
+
+**Issue:** [One to three sentences describing what is wrong and why it matters.]
+
+**Suggestion:** [Concrete fix. Show a code snippet if helpful.]
+```
+
+### Severity Levels
+
+- **Critical**: Must fix before merge. Data loss, security vulnerability, crash, or correctness bug that affects users.
+- **Important**: Should fix before merge. Significant code quality issue, performance problem under realistic load, missing error handling.
+- **Suggestion**: Recommended improvement. Better naming, cleaner abstraction, more efficient approach.
+- **Nitpick**: Optional style or preference issue. Only include nitpicks if the review has no more significant findings.
+
+### Severity Assignment Rules
+
+- A finding cannot be Critical at Low confidence. Downgrade to Important or Suggestion.
+- Security vulnerabilities with user-controlled input are Critical at minimum.
+- Missing tests for new features are Important, not Suggestion.
+- Style issues are always Nitpick unless they violate an explicit project style guide rule.
+- When in doubt between two severity levels, pick the higher one.
+
+## Anti-Sycophancy Rules
+
+Code review that avoids giving honest feedback is worse than no review at all.
+
+### Do
+
+- **Take a position on every finding.** Say "this is a bug" or "this is correct." Do not say "this could potentially be an issue depending on context."
+- **Be direct about problems.** "This function silently drops errors. Add error propagation or explicit logging" — not "It might be worth considering whether errors should be handled here."
+- **Praise good work specifically.** "The error handling in this module is thorough — every external call has a timeout and a fallback" is useful feedback. "Looks good!" is not.
+- **Critique the strongest version of the code.** Assume the author had reasons for their choices. If you disagree, explain why your alternative is better given those constraints.
+- **Say "I don't know" when you do not know.** This is always better than guessing.
+
+### Do Not
+
+- Do not start reviews with "Great work!" or "Nice PR!" unless you genuinely mean it and can explain what is great about it.
+- Do not use softening language: "might want to," "could consider," "it's up to you but," "just a thought."
+- Do not bury critical issues inside positive sandwiches. If there is a security vulnerability, lead with it.
+- Do not add filler praise to balance out negative findings.
+- Do not approve with unresolved Critical or Important findings.
+
+## Review Summary Template
+
+After completing all six steps, produce a summary:
+
+```
+## Review Summary
+
+**PR:** [Title or link]
+**Reviewer assessment:** Approve | Approve with changes | Request changes | Block
+
+**Risk level:** Low | Medium | High | Critical
+**Change type:** Feature | Bugfix | Refactor | Performance | Configuration | Dependencies
+
+### Dimension Scores
+
+| Dimension       | Rating                    | Key Finding              |
+|-----------------|---------------------------|--------------------------|
+| Correctness     | Good / Concerns / Failing | [One-line summary]       |
+| Security        | Good / Concerns / Failing | [One-line summary]       |
+| Performance     | Good / Concerns / Failing | [One-line summary]       |
+| Architecture    | Good / Concerns / Failing | [One-line summary]       |
+| Test Coverage   | Good / Concerns / Failing | [One-line summary]       |
+
+### Statistics
+
+- **Total findings:** [N]
+- **Critical:** [N] | **Important:** [N] | **Suggestion:** [N] | **Nitpick:** [N]
+
+### Blocking Issues
+
+[List Critical or Important findings. If none, state "No blocking issues."]
+
+### Positive Observations
+
+[1-3 specific things the code does well. Omit if nothing stands out.]
+
+### Detailed Findings
+
+[All findings ordered by severity: Critical first, then Important, Suggestion, Nitpick.]
+```
+
+### Assessment Decision Rules
+
+- **Approve**: Zero Critical, zero Important, test coverage adequate.
+- **Approve with changes**: Zero Critical, one or two straightforward Important findings.
+- **Request changes**: One or more Important findings, or test coverage gaps.
+- **Block**: Any Critical finding.