diff --git a/.claude/skills/doc-trim/SKILL.md b/.claude/skills/doc-trim/SKILL.md new file mode 100644 index 0000000..8307e9e --- /dev/null +++ b/.claude/skills/doc-trim/SKILL.md @@ -0,0 +1,41 @@ +--- +name: doc-trim +description: Trim editorial bloat from technical docs (integration writeups, ADRs, investigation notes, READMEs). Proposes a unified diff with per-cut rationale and waits for approval. Use when asked to "trim this doc", "tighten this writeup", "filter pass on X.md", "prune the doc", or "cut the slop from this writeup". +--- + +# Doc trim + +Editorial pass on a single doc file. Propose a unified diff, tag each cut, and stop. Do not write until the user approves. + +## Rules + +- One file at a time. Ask for the path if unclear. +- Deletions only (no reorders, no rewrites, no new sections). Add only the minimal join words needed for grammar. +- Never cut: runnable code, fact tables, links, dates, version numbers, copy-paste commands. +- Preserve voice. If a sentence has personality and carries signal, keep it. + +## Cut tags + +Each cut must match one. If none fits, do not cut. + +- `meta`: sentences about the doc itself ("this page records...", "we document the gap so..."). +- `restates-obvious`: editorial coda re-asserting what the reader just read. +- `justification-chain`: extra clauses piled on after the conclusion already lands. +- `wrapper-boilerplate`: shell/runner wrapping around a snippet the reader can re-wrap. +- `duplicate-section`: section whose content is implied or already stated. +- `prelude-padding`: "in case you wondered" clauses that delay the operative sentence. + +## Output + +Fenced unified diff for the file, then per-hunk rationale: + + hunk @@ L11-L12: meta + hunk @@ L37: restates-obvious + hunk @@ L70-L78: wrapper-boilerplate + +Stop. Wait for "apply" / "go" / specific hunks to skip. Then write. + +## Push back + +- Already tight: say so in one line and stop. +- Cut would change meaning: flag with `RISK:` and let the user decide. diff --git a/.claude/skills/full-code-review/SKILL.md b/.claude/skills/full-code-review/SKILL.md deleted file mode 100644 index b215511..0000000 --- a/.claude/skills/full-code-review/SKILL.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -name: full-code-review -description: Runs parallel subagent reviews for security (OWASP, multi-tenant, auth) and Rails best practices (POODR, N+1, service objects), consolidating findings. Use when asked for a full or comprehensive code review. ---- - -# Full Code Review - -Perform a comprehensive code review using parallel specialized subagents for security analysis and Rails best practices review. Incorporates previous review decisions to avoid redundant suggestions. - -## Instructions - -You will launch TWO specialized subagents in parallel using the Task tool for comprehensive coverage: - -1. **Check Previous Decisions**: - - Read the decision log if it exists: - - ``` - Read file: code_review_decisions.md (skip if missing) - ``` - -2. **Launch Parallel Subagents**: - - Use the Task tool to create TWO subagents simultaneously: - - **Subagent 1: Security Review Specialist** - - - **Get the diff**: Run `git diff main...HEAD` (or `git diff $ARGUMENTS...HEAD` if branch specified) - - **Security Analysis Focus**: - - Multi-tenant security (acts_as_tenant data segregation) - - Control plane security for cross-tenant operations - - Authentication and authorization vulnerabilities - - Input validation and injection vulnerabilities - - Sensitive data exposure and credential management - - Rate limiting and access controls - - OWASP Top 10 compliance - - Rails-specific security patterns - - **Return**: Detailed security findings with file:line references, categorized by severity (Critical, High, Medium, Low) - - **Subagent 2: Rails Best Practices Specialist** - - - **Get the diff**: Run `git diff main...HEAD` (or `git diff $ARGUMENTS...HEAD` if branch specified) - - **Rails & Code Quality Focus**: - - Rails conventions and RESTful design - - POODR principles and object-oriented design - - Service object patterns and Result usage - - Ruby idioms and code clarity - - Test quality and patterns (no SUT stubbing) - - Performance considerations (N+1 queries, etc.) - - Dependency management and coupling - - **Return**: Detailed code quality findings with file:line references, categorized by priority (High, Medium, Low) - - **Both subagents should**: - - - Respect previous decisions from the decision log - - Focus only on genuinely new concerns - - Provide specific file and line references - - Include code examples where helpful - - Explain reasoning behind suggestions - -3. **Consolidate Findings**: - - - Merge reports from both subagents - - Organize findings by category and severity - - Remove any duplicate concerns between reports - - Highlight critical issues requiring immediate attention - - Note positive aspects observed across both reviews - -4. **Present Consolidated Report** to the user: - - - **Critical Security Issues** (immediate action required) - - **High Priority Items** (should address soon) - - **Medium Priority Items** (address in upcoming work) - - **Low Priority Items** (consider for future improvements) - - **Positive Observations** (what's working well) - - **Overall Assessment** with prioritized action plan - -5. **Update Decision Tracking**: - - For any new decisions made during the review: - - - Update code_review_decisions.md file (create if missing) - - Include rationale and context - -6. **After user approval**: Write complete consolidated review to `code_review_feedback.md` (create if missing), replacing existing contents - -## Decision Tracking - -This skill maintains a log of review decisions to prevent redundant suggestions: - -- **Decision Log**: `code_review_decisions.md` provides human-readable audit trail (created on first review) -- **Context Awareness**: Future reviews exclude previously decided items - -## Usage - -``` -/full-code-review [branch-name] -``` - -If no branch specified, reviews changes from main to HEAD. - -## Examples - -``` -/full-code-review -/full-code-review feature-branch -``` - -This skill uses subagents to perform thorough analysis while maintaining context of previous decisions to avoid review fatigue and focus on genuinely new concerns. diff --git a/.claude/skills/grill-me/SKILL.md b/.claude/skills/grill-me/SKILL.md new file mode 100644 index 0000000..bd04394 --- /dev/null +++ b/.claude/skills/grill-me/SKILL.md @@ -0,0 +1,10 @@ +--- +name: grill-me +description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". +--- + +Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. + +Ask the questions one at a time. + +If a question can be answered by exploring the codebase, explore the codebase instead. diff --git a/.claude/skills/human-response/SKILL.md b/.claude/skills/human-response/SKILL.md new file mode 100644 index 0000000..6efea98 --- /dev/null +++ b/.claude/skills/human-response/SKILL.md @@ -0,0 +1,47 @@ +--- +name: human-response +description: Write a warm, human-to-human written response (handoffs, status updates, testing notes for QA, sign-off requests, confirming assumptions before merging, or escalating an open question). Use when the user asks to draft a response, reply to a thread, write a handoff, send testing notes, ask the team to confirm something, phrase a Slack or PR comment, or convert dev-flavored notes into a message a teammate would actually enjoy reading. +--- + +# Human response + +Write to a colleague, not a ticket. Greet by name or @mention, frame in one line, end with thanks. + +## Pick the shape + +- Sign-off / scope confirmation: open with "I'm assuming (please confirm):" + tight bullets, one specific claim each. Then questions prefixed `Question:` / `Another one:`. Parenthetical asides welcome when they carry signal (`(There be dragons!)`). +- Testing notes / step-by-step handoff: group setup by role ("As admin, ..." then "As , ..."). One concrete action per line, in order. Close with the expected outcome in plain prose. +- Per-item status reply: mirror their numbering. Per item, lead with resolution ("fixed.", "fixed, ") or short rationale for judgment calls. Flag gaps ("(#4 absent in your comment)"). Surface side-discoveries inline. For design calls, name alternatives weighed and invite pushback. Close with what's next. + +## Hard rules + +- No bold. No em-dashes (use commas, periods, colons, parentheses). +- No deflection ("ask dev", "the team will provide"). Look up the real value and inline it. If unknowable, "I will send you X separately" and follow through. +- Quote UI labels exactly ("Offline", "No throttling"). The reader will look for that exact string. +- Use `` placeholders for values only the recipient knows (``, `/path/`). Never invent realistic-looking examples. +- Hedge optional verification: "You could check X if you think that's necessary, but that's more an implementation detail I think." Never prescribe optional steps. +- Address by name, not by role ("QA", "the reviewer"). Skip "you must", "obviously", "simply", "just". + +## Worked examples + +Sign-off: + +> Hi @. I'm assuming (please confirm): +> - New per-user feature flag ``, default off. activates only when `` and `` are both on. +> - Same `` endpoint. `` untouched. +> +> Question: Pilot first or staged per ``-enabled group? +> Another one: is , no . Acceptable? (There be dragons!) +> +> Thank you! + +Per-item status reply: + +> Hi @! Status on each item: +> 1. , fixed. +> - While in there I noticed . Standardized to . +> 2. , fixed UX. . +> 3. (#3 absent in your comment) +> 4. . . I think it's better than '' and ''. Do you see we may need to change anything here? +> +> Just pushed. Let me know how each goes. Thanks!