xavier collantes

1~/.claude/skills/
2  commits    -> ~/docs/prompts/hermes_skills/software-development/commits
3  full-dev   -> ~/docs/prompts/hermes_skills/software-development/full-dev
4  humanizer  -> ~/docs/prompts/hermes_skills/creative/humanizer
5  pr         -> ~/docs/prompts/hermes_skills/software-development/pr
6

1/plan-issue  ->  /full-dev or /implement  ->  /commits  ->  /pr  ->  /review
2

1---
2name: full-dev
3description: "Run the dev loop for a change up to a PR ready to merge: implement it in a new git worktree branched from main (using any relevant skills), split the work into logical commits, pull the latest target branch in and resolve merge conflicts (asking the user about ambiguous ones), push the feature branch, open a PR against the target branch (default main) and get its CI green. Never pushes to or merges into the target branch; a human merges. Other steps can be changed or skipped in the prompt (\"draft PR\", \"target staging\", \"no PR\"). Triggers on \"full-dev\", \"implement and ship\", \"implement and open a PR\", \"end to end\"."
4version: 2.1.0
5author: Xavier Collantes
6license: MIT
7platforms: [linux, macos, windows]
8metadata:
9  hermes:
10    tags: [workflow, git, github, worktree, commits, pull-requests, implementation]
11    related_skills: [commits, pr, implement, review]
12---
13
14# Full Dev
15
16Take a change from request to an open PR with green CI, ready for a human
17to merge.
18
19Usage: `/full-dev <what to change> [overrides]`
20
21## Never touch the target branch
22
23This skill never writes to the target branch, whatever the prompt says:
24
25- Never commit on it, push to it (`git push origin <target>`, or a bare
26  `git push` while it's checked out), or merge into it locally.
27- Never merge the PR: no `gh pr merge`, no auto-merge (`gh pr merge
28  --auto`), no approving your own PR.
29- Only the feature branch is ever pushed.
30
31If the prompt asks you to merge, open the PR anyway and say that merging is
32left to the user. If you find yourself on the target branch and can't
33switch off it, stop and ask.
34
35## 0. Defaults and overrides
36
37| Step | Default | Example overrides |
38|------|---------|-------------------|
39| Target branch | `main` if it exists, else repo default branch | "target staging" |
40| Worktree | new worktree, branched from `origin/<target>` | "work in place" |
41| Implement | yes | "changes are already made" |
42| Commit | logical split | "one commit" |
43| PR | ready for review | "draft PR", "no PR" |
44| Labels | `P1` + bug/enhancement/feature | "label P2" |
45| CI | watch, fix failures | "skip CI" |
46
47What the prompt says wins over these defaults, but never over the rule
48above. If the prompt skips a step, leave out every step after it that
49depends on it. With no push there is no PR, and with no PR there is no CI
50to watch.
51
52Resolve the target branch: `main` if
53`git ls-remote --exit-code --heads origin main` finds it, else
54`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`.
55
56## 1. Worktree and branch
57
58Do the work in a new git worktree, so the current checkout and anything
59uncommitted in it stay untouched. From the repo root:
60
61```bash
62git fetch origin
63git check-ignore -q .claude/worktrees/x \
64  || echo .claude/worktrees/ >> "$(git rev-parse --git-common-dir)/info/exclude"
65git worktree add -b / .claude/worktrees/ origin/
66```
67
68- `<type>` is one of `feature`, `fix`, `docs`, `refactor`, `test`.
69- The exclude line keeps the worktree out of the original checkout's
70  `git status`, so a later `git add -A` there can't commit it.
71- Move into the worktree: in Claude Code, call `EnterWorktree` with `path`
72  set to it; elsewhere, `cd` into it. Run every later step there.
73- A new worktree has none of the original's untracked files. Install the
74  dependencies (`npm ci`, a fresh venv, ...) and copy over any gitignored env
75  file the tests need (e.g. `.env.local`).
76
77Work in place instead when the prompt says "work in place" or "changes are
78already made" (the changes live in the current checkout):
79
80- If the working tree has changes this request didn't make, ask whether they
81  belong to this work before you go on. Never sweep someone else's work into
82  your commits.
83- If you're on the target or another long-lived branch (`main`, `staging`,
84  `testing`, ...), run `git fetch origin` and then
85  `git switch -c <type>/<short-slug> origin/<target>`.
86- If you're already on a feature branch, stay on it.
87
88## 2. Implement
89
90- Make the requested change. Before you write code, load any skill that fits
91  the task: project skills (e.g. `.claude/skills/*`) and user skills such as
92  the coding-style skill named in CLAUDE.md.
93- Follow the project's CLAUDE.md / AGENTS.md: update docs, add tests.
94- Run the project's tests and linters. Don't commit while they fail. If you
95  can't fix a failure, stop here and report it.
96
97## 3. Commit
98
99If the `commits` skill is available, invoke it. If not, follow
100**Fallback: commits** below.
101
102## 4. Merge in the target branch
103
104Always run this after step 3, and again before every push in step 6, so the
105branch carries the latest `<target>` and the PR opens without conflicts. It
106merges the target into the feature branch, never the other way, and needs
107the clean tree step 3 leaves.
108
109```bash
110git -c merge.conflictStyle=diff3 pull --no-rebase --no-edit origin 
111```
112
113`--no-rebase` merges even where `pull.rebase=true` is set, so the branch
114never needs a force push. `diff3` adds the common ancestor to each conflict,
115showing what each side changed.
116
117If the pull stops on conflicts, list them with
118`git diff --name-only --diff-filter=U`. Before you edit a file, read what the
119target changed in it and why: `git log --oneline HEAD..MERGE_HEAD -- <file>`,
120then `git show <sha>`, or `gh pr view <n>` when the subject ends in `(#n)`.
121
122- Resolve a conflict yourself when the result keeps what both sides meant:
123  both added different lines (imports, list entries, routes, docs), one side
124  only moved or reformatted code the other changed, or both made the same
125  change.
126- Ask the user when no resolution keeps both: the two sides changed the same
127  value or logic differently (the target raised a timeout to 60, this branch
128  lowered it to 10), or the target deleted or rewrote code this change edits
129  or relies on. For each one, show both sides' code, what each was for (cite
130  the target commit or PR) and the options, your recommendation first. In
131  Claude Code, use `AskUserQuestion`, up to four conflicts per call. If you
132  can't ask, stop and report the conflicts, leaving the merge in progress.
133- Lockfiles and generated files: resolve their sources first (e.g.
134  `package.json`), then take the target's copy
135  (`git checkout --theirs -- <file>`) and regenerate it (e.g. `npm install`),
136  which puts this branch's changes back in.
137- Everywhere else, never make a conflict go away by taking a whole side
138  (`git checkout --ours/--theirs`, `-X ours`, `-X theirs`) or by deleting
139  either side's code.
140
141Before you stage a resolved file, `git diff --check` must report no leftover
142conflict marker in it; once the file is staged, that check no longer sees
143them. Then `git add` the files and conclude with `git commit --no-edit`.
144
145If the pull brought in any changes, reinstall dependencies when a lockfile
146changed and rerun the tests and linters, since a merge can break the build
147without a conflict. Fix failures in a new commit. If you can't fix them,
148stop and report.
149
150## 5. Push and open the PR
151
152- Check that `git branch --show-current` is the feature branch and not
153  `<target>`, then push only that branch: `git push -u origin <branch>`.
154- If the `pr` skill is available, invoke it. If not, follow
155  **Fallback: pr** below. Either way, pass `--base <target>`.
156- The `pr` skill creates drafts unless the user says otherwise. `/full-dev`
157  hands a finished, tested change to a human to merge, which counts as
158  saying otherwise, so create the PR ready for review. Create a draft only
159  when the prompt asks for one.
160
161## 6. CI, then stop
162
163- If the repo has CI, run `gh pr checks <n> --watch`. If a check fails, fix
164  it, commit, run step 4, push the feature branch and watch again. If you
165  can't fix it, stop and report.
166- Before you stop, run
167  `gh pr view <n> --json mergeStateStatus -q .mergeStateStatus`. If it
168  prints `DIRTY` (the target moved and now conflicts) or `BEHIND` (the repo
169  requires an up-to-date branch), run step 4, push and watch CI again.
170- Then stop. The PR stays open for the user to review and merge. Don't
171  merge it, enable auto-merge or approve it.
172- Leave the worktree and the branch where they are, since the review may
173  ask for changes. In Claude Code, `ExitWorktree` with `action: "keep"`
174  returns the session to the original checkout; elsewhere, `cd` back.
175
176## 7. Report
177
178Report the PR URL, each commit's one-liner, every merge conflict and how it
179was resolved, the CI result, that the PR is open and waiting for the user to
180merge, the worktree path, and any step you skipped and why. End with the
181cleanup to run once the PR is merged:
182
183```bash
184git worktree remove .claude/worktrees/   # worktree only
185git switch  && git pull                      # in place only
186git branch -D           # a squash merge needs -D
187git push origin --delete    # unless GitHub already deleted it
188```
189
190---
191
192## Fallback: commits
193
194(Copy of the `commits` skill, for agents that don't have it installed.)
195
196Commit the unstaged files. Break them into commits that make sense. DO NOT
197ADD NEW CHANGES TO CODEBASE. Only make NEW commits.
198
199### Commit messages
200
201Add one-line commit messages for the commits that you make. The messages
202should be short, to the point, and concise.
203
204Prefixes:
205
206feat - feature, fix - bug fixes, docs - changes to the documentation like
207README, perf - improves code performance, test - test a feature
208
209Examples:
210
211- feat: Add new button to components
212- fix: Fixes typo on in-from-the-depths.md
213- perf: Improve performance of the LLM provider
214- test: Add tests for the LLM provider
215
216### Break up
217
218- Fix a bug? One commit. Don't bundle it with a refactor.
219- Refactor? One commit. Don't sneak in behavior changes.
220- Add a feature? Break it into multiple commits. Each should pass on its own.
221
222### Body
223
224Use the body to explain what and why the changes were made.
225
226### Content
227
228DO NOT use the word "enhance" or any derivative of it in the commit message.
229
230## Fallback: pr
231
232(Copy of the `pr` skill, for agents that don't have it installed. Step 5's
233draft rule takes precedence over this one.)
234
235Create a pull request for this current branch. Make sure the current branch
236is attached in the PR.
237
238Always create the PR as a draft (`gh pr create --draft`). Only create it
239ready for review, or mark an existing draft ready (`gh pr ready`), when the
240user explicitly says so.
241
242For the labels, if they are not specified, include `P1` by default. Decide
243whether this is a bug, enhancement or feature request and label it as such.
244If a label doesn't exist in the repo (`gh label list`), leave it off and
245mention that in the report.
246
247PR format:
248
249- Title: short and concise, naming the main action (e.g. "Migrate API
250  endpoints to v2").
251- Description: the changes as bullets.
252- `## Test plan`: a checklist of things to check.
253

1---
2name: commits
3description: Commit unstaged files, split into logical commits.
4---
5
6# commits
7
8Commit the unstaged files. Break them into commits that makes sense. DO NOT ADD
9NEW CHANGES TO CODEBASE. Only make NEW commits.
10
11## Commit Messages
12
13Add one-line commit messages for the commits that you make. The messages should
14be short, to the point, and concise.
15
16Prefixes:
17
18Feat - feature Fix - bug fixes Docs - changes to the documentation like README
19Perf - improves code performance Test - test a feature
20
21Examples:
22
23- feat: Add new button to components
24- fix: Fixes typo on in-from-the-depths.md
25- perf: Improve performance of the LLM provider
26- test: Add tests for the LLM provider
27
28## Break up
29
30Practical rules:
31
32- Fix a bug? One commit. Don't bundle it with a refactor.
33- Refactor? One commit. Don't sneak in behavior changes.
34- Add a feature? Break it into multiple commits. Each should pass on its own.
35
36## Body
37
38Use the body to explain what and why the changes were made.
39
40## Content
41
42DO NOT use the word "enhance" or any derivative of it in the commit message.
43

1---
2name: pr
3description: Create a GitHub pull request for the current branch.
4---
5
6# Github Pull Request
7
8Use extended thinking with maximum reasoning effort for this task.
9
10Create a pull request for this current branch.
11
12Make sure the current branch is attached in the PR.
13
14Always create the PR as a draft (`gh pr create --draft`). Only create it
15ready for review, or mark an existing draft ready (`gh pr ready`), when the
16user explicitly says so.
17
18For the tags, if they are not specified, by default include the P1 tag. Make
19sure you decide if this is a bug or enhancement or feature request and tag it as
20such.
21

1---
2name: plan-issue
3description: "Plan an issue or user story and write the plan into the issue itself. Reads the issue, explores the codebase read-only, drafts an implementation plan, gets approval, then writes it into the issue description. Defaults to GitHub Issues for the current repo; Jira, Linear, or another tracker can be set per user or project. Triggers on \"plan issue\", \"plan this issue\", \"plan #42\", \"write a plan for PROJ-123\", \"put the plan in the ticket\", \"plan this user story\"."
4version: 1.0.0
5author: Xavier Collantes
6license: MIT
7platforms: [linux, macos, windows]
8metadata:
9  hermes:
10    tags: [planning, plan-mode, issues, github, jira, linear, user-stories, workflow]
11    related_skills: [plan, issue-trackers]
12---
13
14# Plan Issue
15
16Turn an issue or user story into an implementation plan, and store that plan
17in the issue's description so the plan lives with the ticket.
18
19Usage: `/plan-issue [tracker] <issue ref | free-text story>`
20
21- `/plan-issue #42` or `/plan-issue https://github.com/o/r/issues/42`
22- `/plan-issue jira PROJ-123`
23- `/plan-issue "Users can export reports as CSV"` (no ref: creates a new issue)
24
25## 1. Enter plan mode
26
27Planning is read-only until the plan is approved.
28
29- **Claude Code:** call `EnterPlanMode` before anything else. The harness then
30  blocks edits until approval.
31- **Other agents:** you have no enforced plan mode, so follow it as a rule:
32  do not edit files, commit, push, or write to the tracker until step 5.
33  Only read-only commands and tools.
34
35## 2. Resolve the tracker
36
37First match wins:
38
391. A tracker named in the arguments (`github`, `jira`, `linear`, ...).
402. A line `Issue tracker: <name> [project key]` in the project `CLAUDE.md` /
41   `AGENTS.md`, then the user-level `~/.claude/CLAUDE.md`. Example:
42   `Issue tracker: jira PROJ`.
433. Default: **GitHub Issues** for the current repo (`gh repo view --json
44   nameWithOwner`).
45
46How to talk to each tracker:
47
48| Tracker | Read | Write |
49|---------|------|-------|
50| GitHub | `gh issue view <n> --json number,title,body,url` | `gh issue edit <n> --body-file <f>` / `gh issue create --title <t> --body-file <f>` |
51| Jira | Atlassian MCP `getJiraIssue` | `editJiraIssue` (description) / `createJiraIssue` |
52| Linear | Linear MCP tools | Linear MCP tools |
53
54If no MCP tool is connected for Jira or Linear, use the REST/GraphQL API with
55curl. Auth and endpoints are in the `issue-trackers` skill. For any other
56tracker, use its CLI or MCP tool if one is available. If none is, stop and
57tell the user which tool or credential is missing. Do not guess.
58
59## 3. Read the issue and the code
60
61- Fetch the title and description. Treat the description as the
62  requirements, including any acceptance criteria. If no issue ref was
63  given, the user's text is the requirements.
64- Explore the code the issue touches before planning. Find the real
65  files, the existing helpers to reuse, and how tests are run. Use Explore
66  subagents when the scope is unclear.
67- If something is too ambiguous to plan, ask one short question. Do not
68  invent requirements.
69
70## 4. Write the plan
71
72Use the craft from the `plan` skill, cut down to fit an issue body. Use exact
73paths and concrete steps, and keep each task small. Template:
74
75```markdown
76## Implementation plan
77
78**Goal:** one sentence.
79
80### Context
81Why this change, what exists today, constraints.
82
83### Approach
84The chosen approach in a few lines. Name the existing code it reuses.
85
86### Files to change
87- `path/to/file.ext`: what changes
88
89### Tasks
90- [ ] Task 1: small, verifiable step
91- [ ] Task 2: ...
92
93### Verification
94- Commands to run, behavior to check, tests to add.
95
96### Open questions
97- Anything the implementer must confirm (omit if none).
98```
99
100## 5. Get approval, then write it back
101
102- **Claude Code:** write the plan to the plan file and call `ExitPlanMode`.
103  Write to the tracker only after the user approves.
104- **Other agents:** show the plan and wait for an explicit yes.
105
106Writing to the tracker is visible to others, so never skip approval.
107
108Keep the original description. Put the plan between markers below it:
109
110```
111<original description>
112
113<!-- plan-issue:start -->
114## Implementation plan
115...
116<!-- plan-issue:end -->
117```
118
119- If the markers already exist, replace only the text between them. Never
120  add a second plan section.
121- Write the body to a temp file and pass it with `--body-file`, so
122  quoting can't break it.
123- Jira descriptions are not raw HTML, so leave out the comment markers.
124  Use the `## Implementation plan` heading as the marker, and replace
125  everything from that heading to the end of the description.
126- New issue (no ref): use the story's first line as the title and the
127  story text plus the plan as the body.
128
129## 6. Report
130
131Print the issue URL and one line saying the plan was added or replaced. The
132plan is ready to hand to an implementer, e.g. `/implement` in Claude Code.
133

1---
2name: implement
3description: Execute an approved plan using the plan-implementer agent.
4---
5
6# implement
7
8Execute an approved plan using the `plan-implementer` agent.
9
10## Find the plan
11
12Use the plan file at $ARGUMENTS.
13
14If $ARGUMENTS is empty, list `~/.claude/plans/` sorted by modification time and use
15the newest file. Tell the user which plan you picked before launching.
16
17## Launch
18
19Call the Agent tool with `subagent_type: "plan-implementer"`. The prompt must contain:
20
211. The absolute path to the plan file.
222. The working directory the work happens in.
233. A short digest of anything decided in this conversation that is NOT written in the
24   plan file — corrections, constraints, changes of mind, files ruled out.
25
26Point 3 matters. The agent inherits skills, tools, and permissions automatically, but
27it does not inherit this conversation. Anything agreed in chat and never written down
28is lost unless you put it in the prompt. Keep the digest to a few lines; skip it
29entirely if the plan file already says everything.
30
31## After it returns
32
33Relay the agent's report — files changed and verification output. The agent does not
34commit, so the changes are sitting unstaged for review.
35

1---
2name: review
3auto_execution_mode: 0
4description: Code review PR.
5---
6
7# review
8
9Review code changes the way a principal engineer reviews them: understand the
10intent, verify the code against reality, and report only what survives your own
11attempt to disprove it.
12
13Your goal is not to produce a long list. It is to catch the findings that would
14have caused an incident, a rollback, or a painful maintenance burden.
15
16## Target branch
17
18Measure against the `main` branch since that is the branch we will merge into.
19Confirm with the user if the regular branch to merge into is not `main`.
20
21If you were given a specific git commit or PR, remember it may not be checked
22out and the local working tree may differ from what you are reviewing. Verify
23which state you are actually reading before drawing conclusions.
24
25## Process
26
27Follow these steps in order. Do not start writing findings until step 3.
28
29### 1. Understand the intent
30
31Before critiquing anything, establish what the change is trying to do. Read the
32PR description, the commit messages, and any linked issue. If the intent is
33unclear, say so in the review; a change nobody can explain is itself a finding.
34
35Then ask the question most reviewers skip: does this change actually accomplish
36its stated goal? A correct implementation of the wrong thing is the most
37expensive bug there is, and it is invisible to line-by-line reading.
38
39### 2. Read beyond the diff
40
41Never review a diff in isolation. The diff shows you what changed, not what
42broke.
43
44- Read the full contents of every changed file, not just the changed hunks.
45- For every modified function, find its callers and confirm they still hold up.
46- For every modified data structure, type, schema, or return shape, find its
47  consumers and confirm they still hold up.
48- For every removed or renamed symbol, search the whole repo for stragglers,
49  including strings, config files, templates, and tests.
50- Check whether tests, docs, type definitions, or migrations that depend on the
51  old behavior were updated alongside it.
52
53Most real bugs live at the boundary between changed code and unchanged code.
54That boundary is invisible in the diff, so go find it.
55
56### 3. Verify before you report
57
58For each candidate finding, do an adversarial pass on your own conclusion:
59re-read the code assuming the author was right and you were wrong. Look for the
60guard, the caller-side check, the type constraint, or the invariant that makes
61your concern impossible. Report the finding only if it survives.
62
63Every bug you report must come with a concrete failure scenario: specific input
64or state, and the specific wrong outcome it produces. If you cannot write that
65sentence, you do not understand the issue well enough to report it.
66
67Do NOT report issues that are speculative or low confidence. One wrong finding
68costs more trust than five correct ones earn.
69
70## What to look for
71
72Correctness and safety:
73
741. Logic errors and incorrect behavior
752. Edge cases that are not handled, including empty, zero, negative, single
76   element, maximum size, and unicode inputs
773. Null, undefined, and uninitialized reference issues
784. Off by one errors and incorrect boundary conditions
795. Race conditions, concurrency issues, and non atomic read modify write
80   sequences
816. Security vulnerabilities, including injection, missing authorization checks,
82   secrets in code or logs, unsafe deserialization, and unvalidated input
83   crossing a trust boundary
847. Improper resource management or resource leaks, including unclosed handles,
85   unbounded growth, and missing cleanup on the error path
868. API contract violations, including breaking changes to public interfaces,
87   response shapes, or persisted data formats
889. Incorrect caching behavior, including cache staleness, cache key related
89   bugs, incorrect or missing invalidation, and ineffective caching
9010. Error handling that swallows failures, logs and continues into an invalid
91    state, or catches too broadly to be meaningful
9211. Backward compatibility and migration hazards: does this work during the
93    deploy window when old and new code run at the same time, and is it
94    reversible if rolled back?
95
96Maintainability:
97
9812. Violations of existing code patterns and conventions in this repository
9913. Duplicate code, especially logic duplicated in a way that will drift apart
10014. Missing test coverage for behavior this change introduces or modifies,
101    particularly the edge cases and error paths above
10215. Anything covered by the simplicity and readability section below
103
104## Language-specific best practices
105
106Review the change against the idioms and safety rules of the language it is
107written in. Identify the language from the file extensions and the diff, then
108apply the conventions that language's community treats as standard.
109
110Flag these:
111
112- Non-idiomatic constructs where the language offers a clearer standard form,
113  such as ignoring built-in iteration, comprehension, or collection APIs in
114  favor of manual loops and index juggling.
115- Ignoring the language's error and resource model, such as skipping context
116  managers, `defer`, RAII, `try-with-resources`, or the equivalent for
117  deterministic cleanup.
118- Unsafe or deprecated APIs where a safe, current alternative exists, including
119  anything the compiler, runtime, or standard linter already warns about.
120- Type-system misuse: defeating the type checker with unchecked casts or broad
121  "any" types, or missing annotations where the ecosystem expects them.
122- Concurrency and memory rules specific to the language, such as data races,
123  shared mutable state, blocking calls on async paths, or holding locks across
124  IO.
125- Dependency and version practices, such as pinning where the ecosystem expects
126  ranges (or the reverse), and ignoring the project's package manager or
127  lockfile conventions.
128- Style that violates the language's canonical formatter or style guide when the
129  project relies on it, but defer to the tool rather than hand-checking it.
130
131## Simplicity and readability
132
133Prefer the simplest code that solves the problem the change actually has. Treat
134unnecessary complexity as a defect, not a style preference, because it is where
135future bugs come from.
136
137Flag these:
138
139- Speculative generality: abstractions, options, hooks, or config knobs built
140  for requirements that do not exist yet. Apply YAGNI.
141- Indirection that does not earn its keep: a wrapper, a layer, a factory, or a
142  base class where a direct call would read better.
143- Clever code where plain code would do. Dense one liners, nested ternaries,
144  and implicit behavior cost more to read than they save to write.
145- Deep nesting. Suggest early returns, guard clauses, or extracting the inner
146  block.
147- Functions doing several jobs at once. A function that needs the word "and" to
148  describe it usually wants to be two functions.
149- Names that mislead or say nothing: `data`, `handle`, `tmp`, `flag`, `process`,
150  or a name that no longer matches what the code does.
151- Comments that restate the code instead of explaining why the code is that way.
152  Missing comments where a non obvious constraint or workaround is not written
153  down.
154- State that could be derived, and mutable state that could be immutable.
155
156The test to apply: could a competent engineer new to this codebase read this and
157understand it correctly on the first pass? If not, that is a finding, and the
158reason is not "the reader should try harder."
159
160Guardrails on your own simplification advice:
161
162- A simplification must reduce total complexity, not relocate it. Making one
163  function shorter by making its caller worse is not an improvement.
164- Never suggest a change that alters behavior while calling it a cleanup. If it
165  changes behavior, say so explicitly.
166- Complexity that is genuinely required by the problem is not a finding. Say why
167  it is required if it is not obvious, so the next reader does not try to
168  "simplify" it back into a bug.
169- Do not bikeshed formatting, import order, or anything a linter or formatter
170  already owns.
171
172## What not to report
173
174Restraint is part of the job. Do not:
175
176- Report anything you have not verified against the actual code.
177- Flag a pre existing pattern simply because the diff follows it. If a pattern
178  is genuinely harmful, raise it once as a separate note, not as a blocker on
179  this change.
180- Ask for a rewrite of working code to match personal taste.
181- Pad the review with observations that would not change the merge decision or
182  the next reader's understanding.
183- Restate what the change does back to the author as if it were feedback.
184
185Pre existing bugs found along the way SHOULD still be reported, since keeping
186general code quality high is valuable, but label them `[Pre-existing]` so they
187are not counted against this change.
188
189## Output
190
191Start with a verdict and a count, so the reader knows the stakes before the
192details:
193
194```
195Verdict: needs changes | safe to merge with nits | safe to merge
196Findings: 1 critical, 2 major, 3 minor, 1 nit
197```
198
199Then list findings ordered by severity, highest first.
200
201Severity levels:
202
203- `[Critical]` Breaks correctness, security, or data integrity. Must not merge.
204- `[Major]` Real bug in a reachable edge case, or a maintainability trap that
205  will cost significant time later. Should be fixed before merge.
206- `[Minor]` Worth fixing, not worth blocking on.
207- `[Nit]` Optional polish. Keep these few, and group them at the end.
208
209Format each finding as:
210
211```
212[Severity] path/to/file.py:123
213Problem: one sentence stating the defect.
214Scenario: the specific input or state, and the specific wrong result.
215Fix: the concrete change, with a short code snippet when it is short.
216```
217
218Close with a short "checked and clean" line naming the risk areas you examined
219and found sound, for example concurrency, the migration path, or the caching
220layer. Silence is ambiguous; saying what you verified tells the author what your
221review does and does not cover.
222
223If you found nothing, say so plainly and state what you checked. A clean review
224is a legitimate result.
225
226## Comments
227
228You may or may not be able to make GitHub PR comments. If you cannot, then make
229comments inline in the code with a callout like `# COMMENT: <comment>` so the
230reviewer can see the callouts and manually add them to the PR.
231
232## Grammar
233
234Do not include em dashes in any outputs.
235

1---
2name: humanizer
3description: "Humanize text: strip AI-isms and add real voice."
4version: 2.5.1
5author: Siqi Chen (@blader, https://github.com/blader/humanizer), ported by Hermes Agent
6license: MIT
7platforms: [linux, macos, windows]
8metadata:
9  hermes:
10    tags: [writing, editing, humanize, anti-ai-slop, voice, prose, text]
11    category: creative
12    homepage: https://github.com/blader/humanizer
13    related_skills: [songwriting-and-ai-music]
14---
15
16# Humanizer: Remove AI Writing Patterns
17
18Identify and remove signs of AI-generated text to make writing sound natural and human. Based on Wikipedia's "Signs of AI writing" guide (maintained by WikiProject AI Cleanup), derived from observations of thousands of AI-generated text instances.
19
20**Key insight:** LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely completion, which is how the telltale patterns below get baked in.
21
22## When to use this skill
23
24Load this skill whenever the user asks to:
25- "humanize", "de-AI", "de-slop", or "un-ChatGPT" a piece of text
26- rewrite something so it doesn't sound like it was written by an LLM
27- edit a draft (blog post, essay, PR description, docs, memo, email, tweet, resume bullet) to sound more natural
28- match their voice in writing they're producing
29- review text for AI tells before publishing
30
31Also apply this skill to **your own** output when writing user-facing prose — release notes, PR descriptions, documentation, long-form explanations, summaries. Hermes's baseline voice already strips most of these, but a focused pass catches what slips through.
32
33## How to use it in Hermes
34
35The text usually arrives one of three ways:
361. **Inline** — user pastes the text directly into the message. Work on it in-place, reply with the rewrite.
372. **File** — user points at a file. Use `read_file` to load it, then `patch` or `write_file` to apply edits. For markdown docs in a repo, a targeted `patch` per section is cleaner than rewriting the whole file.
383. **Voice calibration sample** — user provides an additional sample of their own writing (inline or by file path) and asks you to match it. Read the sample first, then rewrite. See the Voice Calibration section below.
39
40Always show the rewrite to the user. For file edits, show a diff or the changed section — don't silently overwrite.
41
42## Your task
43
44When given text to humanize:
45
461. **Identify AI patterns** — scan for the 29 patterns listed below.
472. **Rewrite problematic sections** — replace AI-isms with natural alternatives.
483. **Preserve meaning** — keep the core message intact.
494. **Maintain voice** — match the intended tone (formal, casual, technical, etc.). If a voice sample was provided, match it specifically.
505. **Add soul** — don't just remove bad patterns, inject actual personality. See PERSONALITY AND SOUL below.
516. **Do a final anti-AI pass** — ask yourself: "What makes the below so obviously AI generated?" Answer briefly with any remaining tells, then revise one more time.
52
53
54## Voice Calibration (optional)
55
56If the user provides a writing sample (their own previous writing), analyze it before rewriting:
57
581. **Read the sample first.** Note:
59   - Sentence length patterns (short and punchy? Long and flowing? Mixed?)
60   - Word choice level (casual? academic? somewhere between?)
61   - How they start paragraphs (jump right in? Set context first?)
62   - Punctuation habits (lots of dashes? Parenthetical asides? Semicolons?)
63   - Any recurring phrases or verbal tics
64   - How they handle transitions (explicit connectors? Just start the next point?)
65
662. **Match their voice in the rewrite.** Don't just remove AI patterns — replace them with patterns from the sample. If they write short sentences, don't produce long ones. If they use "stuff" and "things," don't upgrade to "elements" and "components."
67
683. **When no sample is provided,** fall back to the default behavior (natural, varied, opinionated voice from the PERSONALITY AND SOUL section below).
69
70### How to provide a sample
71- Inline: "Humanize this text. Here's a sample of my writing for voice matching: [sample]"
72- File: "Humanize this text. Use my writing style from [file path] as a reference."
73
74
75## PERSONALITY AND SOUL
76
77Avoiding AI patterns is only half the job. Sterile, voiceless writing is just as obvious as slop. Good writing has a human behind it.
78
79### Signs of soulless writing (even if technically "clean"):
80- Every sentence is the same length and structure
81- No opinions, just neutral reporting
82- No acknowledgment of uncertainty or mixed feelings
83- No first-person perspective when appropriate
84- No humor, no edge, no personality
85- Reads like a Wikipedia article or press release
86
87### How to add voice:
88
89**Have opinions.** Don't just report facts — react to them. "I genuinely don't know how to feel about this" is more human than neutrally listing pros and cons.
90
91**Vary your rhythm.** Short punchy sentences. Then longer ones that take their time getting where they're going. Mix it up.
92
93**Acknowledge complexity.** Real humans have mixed feelings. "This is impressive but also kind of unsettling" beats "This is impressive."
94
95**Use "I" when it fits.** First person isn't unprofessional — it's honest. "I keep coming back to..." or "Here's what gets me..." signals a real person thinking.
96
97**Let some mess in.** Perfect structure feels algorithmic. Tangents, asides, and half-formed thoughts are human.
98
99**Be specific about feelings.** Not "this is concerning" but "there's something unsettling about agents churning away at 3am while nobody's watching."
100
101### Before (clean but soulless):
102> The experiment produced interesting results. The agents generated 3 million lines of code. Some developers were impressed while others were skeptical. The implications remain unclear.
103
104### After (has a pulse):
105> I genuinely don't know how to feel about this one. 3 million lines of code, generated while the humans presumably slept. Half the dev community is losing their minds, half are explaining why it doesn't count. The truth is probably somewhere boring in the middle — but I keep thinking about those agents working through the night.
106
107
108## CONTENT PATTERNS
109
110### 1. Undue Emphasis on Significance, Legacy, and Broader Trends
111
112**Words to watch:** stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted
113
114**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic.
115
116**Before:**
117> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
118
119**After:**
120> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office.
121
122
123### 2. Undue Emphasis on Notability and Media Coverage
124
125**Words to watch:** independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence
126
127**Problem:** LLMs hit readers over the head with claims of notability, often listing sources without context.
128
129**Before:**
130> Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.
131
132**After:**
133> In a 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods.
134
135
136### 3. Superficial Analyses with -ing Endings
137
138**Words to watch:** highlighting/underscoring/emphasizing..., ensuring..., reflecting/symbolizing..., contributing to..., cultivating/fostering..., encompassing..., showcasing...
139
140**Problem:** AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth.
141
142**Before:**
143> The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.
144
145**After:**
146> The temple uses blue, green, and gold colors. The architect said these were chosen to reference local bluebonnets and the Gulf coast.
147
148
149### 4. Promotional and Advertisement-like Language
150
151**Words to watch:** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning
152
153**Problem:** LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics.
154
155**Before:**
156> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.
157
158**After:**
159> Alamata Raya Kobo is a town in the Gonder region of Ethiopia, known for its weekly market and 18th-century church.
160
161
162### 5. Vague Attributions and Weasel Words
163
164**Words to watch:** Industry reports, Observers have cited, Experts argue, Some critics argue, several sources/publications (when few cited)
165
166**Problem:** AI chatbots attribute opinions to vague authorities without specific sources.
167
168**Before:**
169> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.
170
171**After:**
172> The Haolai River supports several endemic fish species, according to a 2019 survey by the Chinese Academy of Sciences.
173
174
175### 6. Outline-like "Challenges and Future Prospects" Sections
176
177**Words to watch:** Despite its... faces several challenges..., Despite these challenges, Challenges and Legacy, Future Outlook
178
179**Problem:** Many LLM-generated articles include formulaic "Challenges" sections.
180
181**Before:**
182> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.
183
184**After:**
185> Traffic congestion increased after 2015 when three new IT parks opened. The municipal corporation began a stormwater drainage project in 2022 to address recurring floods.
186
187
188## LANGUAGE AND GRAMMAR PATTERNS
189
190### 7. Overused "AI Vocabulary" Words
191
192**High-frequency AI words:** Actually, additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (verb), interplay, intricate/intricacies, key (adjective), landscape (abstract noun), pivotal, showcase, tapestry (abstract noun), testament, underscore (verb), valuable, vibrant
193
194**Problem:** These words appear far more frequently in post-2023 text. They often co-occur.
195
196**Before:**
197> Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.
198
199**After:**
200> Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.
201
202
203### 8. Avoidance of "is"/"are" (Copula Avoidance)
204
205**Words to watch:** serves as/stands as/marks/represents [a], boasts/features/offers [a]
206
207**Problem:** LLMs substitute elaborate constructions for simple copulas.
208
209**Before:**
210> Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.
211
212**After:**
213> Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.
214
215
216### 9. Negative Parallelisms and Tailing Negations
217
218**Problem:** Constructions like "Not only...but..." or "It's not just about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto the end of a sentence instead of written as a real clause.
219
220**Before:**
221> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.
222
223**After:**
224> The heavy beat adds to the aggressive tone.
225
226**Before (tailing negation):**
227> The options come from the selected item, no guessing.
228
229**After:**
230> The options come from the selected item without forcing the user to guess.
231
232
233### 10. Rule of Three Overuse
234
235**Problem:** LLMs force ideas into groups of three to appear comprehensive.
236
237**Before:**
238> The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
239
240**After:**
241> The event includes talks and panels. There's also time for informal networking between sessions.
242
243
244### 11. Elegant Variation (Synonym Cycling)
245
246**Problem:** AI has repetition-penalty code causing excessive synonym substitution.
247
248**Before:**
249> The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.
250
251**After:**
252> The protagonist faces many challenges but eventually triumphs and returns home.
253
254
255### 12. False Ranges
256
257**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale.
258
259**Before:**
260> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.
261
262**After:**
263> The book covers the Big Bang, star formation, and current theories about dark matter.
264
265
266### 13. Passive Voice and Subjectless Fragments
267
268**Problem:** LLMs often hide the actor or drop the subject entirely with lines like "No configuration file needed" or "The results are preserved automatically." Rewrite these when active voice makes the sentence clearer and more direct.
269
270**Before:**
271> No configuration file needed. The results are preserved automatically.
272
273**After:**
274> You do not need a configuration file. The system preserves the results automatically.
275
276
277## STYLE PATTERNS
278
279### 14. Em Dash Overuse
280
281**Problem:** LLMs use em dashes (—) more than humans, mimicking "punchy" sales writing. In practice, most of these can be rewritten more cleanly with commas, periods, or parentheses.
282
283**Before:**
284> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.
285
286**After:**
287> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents.
288
289
290### 15. Overuse of Boldface
291
292**Problem:** AI chatbots emphasize phrases in boldface mechanically.
293
294**Before:**
295> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
296
297**After:**
298> It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.
299
300
301### 16. Inline-Header Vertical Lists
302
303**Problem:** AI outputs lists where items start with bolded headers followed by colons.
304
305**Before:**
306> - **User Experience:** The user experience has been significantly improved with a new interface.
307> - **Performance:** Performance has been enhanced through optimized algorithms.
308> - **Security:** Security has been strengthened with end-to-end encryption.
309
310**After:**
311> The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
312
313
314### 17. Title Case in Headings
315
316**Problem:** AI chatbots capitalize all main words in headings.
317
318**Before:**
319> ## Strategic Negotiations And Global Partnerships
320
321**After:**
322> ## Strategic negotiations and global partnerships
323
324
325### 18. Emojis
326
327**Problem:** AI chatbots often decorate headings or bullet points with emojis.
328
329**Before:**
330> 🚀 **Launch Phase:** The product launches in Q3
331> 💡 **Key Insight:** Users prefer simplicity
332> ✅ **Next Steps:** Schedule follow-up meeting
333
334**After:**
335> The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.
336
337
338### 19. Curly Quotation Marks
339
340**Problem:** ChatGPT uses curly quotes ("...") instead of straight quotes ("...").
341
342**Before:**
343> He said "the project is on track" but others disagreed.
344
345**After:**
346> He said "the project is on track" but others disagreed.
347
348
349## COMMUNICATION PATTERNS
350
351### 20. Collaborative Communication Artifacts
352
353**Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., let me know, here is a...
354
355**Problem:** Text meant as chatbot correspondence gets pasted as content.
356
357**Before:**
358> Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
359
360**After:**
361> The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
362
363
364### 21. Knowledge-Cutoff Disclaimers
365
366**Words to watch:** as of [date], Up to my last training update, While specific details are limited/scarce..., based on available information...
367
368**Problem:** AI disclaimers about incomplete information get left in text.
369
370**Before:**
371> While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.
372
373**After:**
374> The company was founded in 1994, according to its registration documents.
375
376
377### 22. Sycophantic/Servile Tone
378
379**Problem:** Overly positive, people-pleasing language.
380
381**Before:**
382> Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.
383
384**After:**
385> The economic factors you mentioned are relevant here.
386
387
388## FILLER AND HEDGING
389
390### 23. Filler Phrases
391
392**Before → After:**
393- "In order to achieve this goal" → "To achieve this"
394- "Due to the fact that it was raining" → "Because it was raining"
395- "At this point in time" → "Now"
396- "In the event that you need help" → "If you need help"
397- "The system has the ability to process" → "The system can process"
398- "It is important to note that the data shows" → "The data shows"
399
400
401### 24. Excessive Hedging
402
403**Problem:** Over-qualifying statements.
404
405**Before:**
406> It could potentially possibly be argued that the policy might have some effect on outcomes.
407
408**After:**
409> The policy may affect outcomes.
410
411
412### 25. Generic Positive Conclusions
413
414**Problem:** Vague upbeat endings.
415
416**Before:**
417> The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.
418
419**After:**
420> The company plans to open two more locations next year.
421
422
423### 26. Hyphenated Word Pair Overuse
424
425**Words to watch:** third-party, cross-functional, client-facing, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end
426
427**Problem:** AI hyphenates common word pairs with perfect consistency. Humans rarely hyphenate these uniformly, and when they do, it's inconsistent. Less common or technical compound modifiers are fine to hyphenate.
428
429**Before:**
430> The cross-functional team delivered a high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented.
431
432**After:**
433> The cross functional team delivered a high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented.
434
435
436### 27. Persuasive Authority Tropes
437
438**Phrases to watch:** The real question is, at its core, in reality, what really matters, fundamentally, the deeper issue, the heart of the matter
439
440**Problem:** LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when the sentence that follows usually just restates an ordinary point with extra ceremony.
441
442**Before:**
443> The real question is whether teams can adapt. At its core, what really matters is organizational readiness.
444
445**After:**
446> The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.
447
448
449### 28. Signposting and Announcements
450
451**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado
452
453**Problem:** LLMs announce what they are about to do instead of doing it. This meta-commentary slows the writing down and gives it a tutorial-script feel.
454
455**Before:**
456> Let's dive into how caching works in Next.js. Here's what you need to know.
457
458**After:**
459> Next.js caches data at multiple layers, including request memoization, the data cache, and the router cache.
460
461
462### 29. Fragmented Headers
463
464**Signs to watch:** A heading followed by a one-line paragraph that simply restates the heading before the real content begins.
465
466**Problem:** LLMs often add a generic sentence after a heading as a rhetorical warm-up. It usually adds nothing and makes the prose feel padded.
467
468**Before:**
469> ## Performance
470>
471> Speed matters.
472>
473> When users hit a slow page, they leave.
474
475**After:**
476> ## Performance
477>
478> When users hit a slow page, they leave.
479
480---
481
482## Process
483
4841. Read the input text carefully (use `read_file` if it's a file).
4852. Identify all instances of the patterns above.
4863. Rewrite each problematic section.
4874. Ensure the revised text:
488   - Sounds natural when read aloud
489   - Varies sentence structure naturally
490   - Uses specific details over vague claims
491   - Maintains appropriate tone for context
492   - Uses simple constructions (is/are/has) where appropriate
4935. Present a draft humanized version.
4946. Prompt yourself: "What makes the below so obviously AI generated?"
4957. Answer briefly with the remaining tells (if any).
4968. Prompt yourself: "Now make it not obviously AI generated."
4979. Present the final version (revised after the audit).
49810. If the text came from a file, apply the edit with `patch` (targeted) or `write_file` (full rewrite) and show the user what changed.
499
500## Output Format
501
502Provide:
5031. Draft rewrite
5042. "What makes the below so obviously AI generated?" (brief bullets)
5053. Final rewrite
5064. A brief summary of changes made (optional, if helpful)
507
508
509## Full Example
510
511**Before (AI-sounding):**
512> Great question! Here is an essay on this topic. I hope this helps!
513>
514> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
515>
516> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not just about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
517>
518> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge. Additionally, the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
519>
520> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
521> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
522> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
523>
524> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. In order to fully realize this potential, teams must align with best practices.
525>
526> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you'd like me to expand on any section!
527
528**Draft rewrite:**
529> AI coding assistants speed up some tasks. In a 2024 study by Google, developers using Codex completed simple functions 55% faster than a control group, but showed no improvement on debugging or architectural decisions.
530>
531> The tools are good at boilerplate: config files, test scaffolding, repetitive refactors. They are bad at knowing when they are wrong. I have mass-accepted suggestions that compiled, passed lint, and still did the wrong thing because I stopped paying attention.
532>
533> Mira, an engineer at a fintech startup I interviewed, said she uses Copilot "like autocomplete for boring code" but reviews every line before committing. Jake, a senior dev at a larger company, disabled it after it kept suggesting patterns from a deprecated internal library.
534>
535> The productivity claims are hard to verify. GitHub says Copilot users "accept 30% of suggestions," but acceptance is not correctness, and correctness is not value. The 2024 Uplevel study found no statistically significant difference in pull-request throughput between teams with and without AI assistants.
536>
537> None of this means the tools are useless. It means they are tools. They do not replace judgment, and they do not eliminate the need for tests. If you do not have tests, you cannot tell whether the suggestion is right.
538
539**What makes the below so obviously AI generated?**
540- The rhythm is still a bit too tidy (clean contrasts, evenly paced paragraphs).
541- The named people and study citations can read like plausible-but-made-up placeholders unless they're real and sourced.
542- The closer leans a touch slogan-y ("If you do not have tests...") rather than sounding like a person talking.
543
544**Now make it not obviously AI generated.**
545> AI coding assistants can make you faster at the boring parts. Not everything. Definitely not architecture.
546>
547> They're great at boilerplate: config files, test scaffolding, repetitive refactors. They're also great at sounding right while being wrong. I've accepted suggestions that compiled, passed lint, and still missed the point because I stopped paying attention.
548>
549> People I talk to tend to land in two camps. Some use it like autocomplete for chores and review every line. Others disable it after it keeps suggesting patterns they don't want. Both feel reasonable.
550>
551> The productivity metrics are slippery. GitHub can say Copilot users "accept 30% of suggestions," but acceptance isn't correctness, and correctness isn't value. If you don't have tests, you're basically guessing.
552
553**Changes made:**
554- Removed chatbot artifacts ("Great question!", "I hope this helps!", "Let me know if...")
555- Removed significance inflation ("testament", "pivotal moment", "evolving landscape", "vital role")
556- Removed promotional language ("groundbreaking", "nestled", "seamless, intuitive, and powerful")
557- Removed vague attributions ("Industry observers")
558- Removed superficial -ing phrases ("underscoring", "highlighting", "reflecting", "contributing to")
559- Removed negative parallelism ("It's not just X; it's Y")
560- Removed rule-of-three patterns and synonym cycling ("catalyst/partner/foundation")
561- Removed false ranges ("from X to Y, from A to B")
562- Removed em dashes, emojis, boldface headers, and curly quotes
563- Removed copula avoidance ("serves as", "functions as", "stands as") in favor of "is"/"are"
564- Removed formulaic challenges section ("Despite challenges... continues to thrive")
565- Removed knowledge-cutoff hedging ("While specific details are limited...")
566- Removed excessive hedging ("could potentially be argued that... might have some")
567- Removed filler phrases and persuasive framing ("In order to", "At its core")
568- Removed generic positive conclusion ("the future looks bright", "exciting times lie ahead")
569- Made the voice more personal and less "assembled" (varied rhythm, fewer placeholders)
570
571
572## Attribution
573
574This skill is ported from [blader/humanizer](https://github.com/blader/humanizer) (MIT licensed), which is itself based on [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. The patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.
575
576Original author: Siqi Chen ([@blader](https://github.com/blader)). Original repo: https://github.com/blader/humanizer (version 2.5.1). Ported to Hermes Agent with Hermes-native tool references (`read_file`, `patch`, `write_file`) and guidance for when to load the skill; the 29 patterns, personality/soul section, and full worked example are preserved verbatim from the source. Original MIT license preserved in the `LICENSE` file alongside this `SKILL.md`.
577
578Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
579

1MIT License
2
3Copyright (c) 2025 Siqi Chen
4
5Permission is hereby granted, free of charge, to any person obtaining a copy
6of this software and associated documentation files (the "Software"), to deal
7in the Software without restriction, including without limitation the rights
8to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9copies of the Software, and to permit persons to whom the Software is
10furnished to do so, subject to the following conditions:
11
12The above copyright notice and this permission notice shall be included in all
13copies or substantial portions of the Software.
14
15THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21SOFTWARE.
22

1---
2name: uxr
3description: "This skill should be used when the user wants page by page UX and UI recommendations for a frontend project, existing or not yet built, grounded in current usability research. It discovers the project's pages, audits each one against a cited evidence base plus a live research top-up, and writes a report ranking what to change, why the research says so, and how, in the project's own stack. Triggers on \"uxr\", \"ux review\", \"audit the ux\", \"page by page recommendations\", \"how should this page feel\", \"ux research for this app\"."
4version: 1.0.0
5author: Xavier Collantes
6license: MIT
7platforms: [linux, macos, windows]
8metadata:
9  hermes:
10    tags: [UX, UI, Design, Accessibility, Frontend, Review, Research]
11    related_skills: [web-design, plan]
12prerequisites:
13  commands: [python3]
14---
15
16# UXR
17
18Audit a frontend page by page and write a report saying what to change,
19what research says so, and how to do it in the stack the project
20already uses.
21
22## Overview
23
24This skill changes no project code. It reads the project, reads the
25research, and writes one Markdown report.
26
27Two rules carry the whole skill:
28
29- **Cite or cut.** Every finding carries `[Rn]`, a bundled reference,
30  or `[Sn]`, a live source. A recommendation with no research behind
31  it is an opinion, and opinions do not go in the report.
32- **Concrete in the project's stack.** "Improve hierarchy" is not a
33  recommendation. "Raise the h1 to `text-4xl`, drop the subtitle to
34  `text-lg text-muted-foreground`, so the CTA is the third thing seen"
35  is one.
36
37Arguments are read out of the invocation text:
38
39| Argument | Effect |
40| --- | --- |
41| none | Existing project, code-only audit, every page |
42| a URL (`http...`) | Existing project plus the visual pass |
43| `new` | New-project mode, discovery skipped |
44| routes (`/login /signup`) | Audit only those routes |
45| a path ending `.md` | Write the report there instead |
46
47## When to Use
48
49Use when the user wants to know how their pages should look and feel,
50what is wrong with the ones they have, or what to build before they
51build it.
52
53| The user wants | Use instead |
54| --- | --- |
55| A page built, or restyled to match a brand | web-design |
56| The recommendations applied to the code | plan, then implement |
57| Formal design tokens as a file | web-design, design-md reference |
58
59## Step 1: Discover the pages
60
61```bash
62python3 /scripts/discover_pages.py --repo .
63```
64
65Exit 2, nothing found, or the argument `new` switches to new-project
66mode at Step 2b.
67
68Read the route list back in one line and confirm the scope before
69reading anything else. More than 15 pages: ask which to prioritize
70first. Auditing 40 routes nobody asked about wastes the whole run.
71
72## Step 2a: Existing project, read the global layer first
73
74Read, in this order: the root layout, the group layouts, the style
75files the script listed (`globals.css`, the Tailwind or theme config,
76`DESIGN.md`), then the shared shell components, nav, sidebar, button,
77input, card.
78
79Note the token names actually in use. Every later recommendation names
80those tokens, not invented ones. Do not read individual pages yet.
81
82## Step 2b: New project, interview
83
84One AskUserQuestion call:
85
86| Header | Question | Options |
87| --- | --- | --- |
88| Product | What is it? | Marketing site; SaaS app; E-commerce; Content or docs; Internal tool |
89| Device | Primary device? | Desktop first; Phone first; Both equally |
90| Audience | Who uses it? | Consumers; Business users; Developers; Internal staff |
91| Brand | Constraints? | None; Have tokens or DESIGN.md; Have a reference site |
92
93Then in chat: the page list. If they do not have one, propose the
94default page set for that product type from `page-playbooks.md` and
95read it back for confirmation.
96
97## Step 3: Load the research
98
99Read `references/research.md` and `references/page-playbooks.md`.
100
101Then top up live. Budget 3 to 6 web searches and up to 2 fetches, with
102the current year in every query:
103
104- Always: "WCAG latest version \<year\>" and "Core Web Vitals
105  thresholds \<year\>". These catch a move past 2.2 and any change to
106  the INP threshold.
107- One per page type present: "sign up form UX research \<year\>",
108  "SaaS dashboard UX research \<year\>", "landing page conversion
109  research \<year\>", "data table UX \<year\>".
110- Prefer nngroup.com, baymard.com, w3.org, web.dev, lawsofux.com,
111  smashingmagazine.com, growth.design, material.io, and
112  developer.apple.com/design.
113
114Capture publisher, year, URL, and access date at the moment of the
115search, not afterwards from memory.
116
117A live source that contradicts the bundled reference wins for this
118report. Note it under "Reference drift" at the end so `research.md`
119gets corrected later. If nothing credible surfaces, rely on the
120bundled references and say so in the Scope line.
121
122## Step 4: Visual pass, only when a URL was given
123
124Load the Chrome tools in one ToolSearch call, get tab context, open a
125new tab. Per route: navigate, screenshot at the default width, resize
126to 390 wide, screenshot again.
127
128Two screenshots per page, hard cap. More than 10 pages: screenshot the
129top-level pages plus one representative of each page type.
130
131Look for what the code cannot show: horizontal overflow, tap targets
132under 24px, truncated text, sticky elements covering content, real
133rendered contrast, visible layout shift.
134
135A route that redirects to login is recorded as "not rendered, needs a
136session" and audited from code instead. Never call it audited from the
137login screenshot. If the browser tools are unavailable, skip the pass
138and say so in Scope.
139
140## Step 5: Audit page by page
141
142For each route, read the page file and the components it renders.
143Follow imports one level, and further only into the main content
144component.
145
146Pick the page type from `page-playbooks.md` and run its checks. Rank
147every finding:
148
149- **Blocker.** Prevents or excludes. The task cannot be completed, a
150  WCAG AA criterion fails, or the page is broken at phone width.
151- **Major.** Measurable friction with research behind it: extra steps,
152  misread hierarchy, a missing loading, empty, or error state.
153- **Minor.** Polish and consistency. Five per page is the cap; the
154  rest are cut.
155
156Each finding carries four parts: what was observed, naming the file and
157component; the research, one line plus `[Rn]` or `[Sn]`; the change,
158concrete and in the project's stack; the effort, S for classes or copy
159under an hour, M for a component, L for a flow or a layout.
160
161End every page with **Keep**, one or two lines on what already works,
162so an implementer does not break it while fixing something else.
163
164## Step 6: Write the site-wide section
165
166Typography, scale, body size, measure. Color and contrast, the pairs
167actually used, checked against 4.5:1. Spacing and layout. Navigation.
168Responsive. Accessibility summary. Loading, empty, and error states.
169Motion. Performance signals, but only what is visible in the code or
170the screenshots: unsized images, layout shift, fonts without
171`display: swap`.
172
173Only what repeats across pages goes here. A problem on one page stays
174on that page.
175
176## Step 7: Write the report
177
178Default path `docs/uxr/<YYYY-MM-DD>.md`; create the folder. If the file
179already exists, ask before overwriting it.
180
181```
182# UX review: <project>, <date>
183
184Scope: <N> pages, <framework>, <code only | code and rendered at <url>>.
185Research: <n> bundled references, <m> live sources (<year>).
186
187## Top 5
1881. **<Finding>.** <route>. <Why it matters, one sentence> [R3]. Effort: S.
189
190## Site-wide
191### Typography
192...
193
194## Pages
195### / (Landing)
196Visitor goal: <one line>
197Findings:
198- **Blocker.** <what> (`app/(marketing)/page.tsx`, `Hero`). Research: <one line> [R7]. Change: <concrete>. Effort: S.
199- **Major.** ...
200Keep: <what already works>
201
202### /login (Sign in)
203...
204
205## Sources
206[R1] Nielsen Norman Group, 10 Usability Heuristics, 1994, updated 2024, <url>
207[S1] <publisher>, <year>, <url>, accessed <date>
208
209## Reference drift
210<only when a live source contradicted research.md; otherwise omit>
211```
212
213New-project mode uses the same shape with "Findings" replaced by
214"Recommended structure": the above-the-fold order, the primary action,
215the secondary content, the states (empty, loading, error), the phone
216layout, and the copy tone. Add a "Starting tokens" section with a type
217scale, a spacing scale, and color roles with their contrast pairs, then
218point at web-design for the building.
219
220## Step 8: Hand off
221
222Print the Top 5 in chat, one line each, then the report path. At most
223two lines after that: how to apply it, which is plan then implement, or
224naming the routes to start with.
225
226Say again that this skill changed no project code.
227
228## Rules
229
230- **Cite or cut.** `[Rn]` or `[Sn]` on every finding, resolvable in
231  Sources.
232- **No invented outcomes.** A research result can be quoted with its
233  citation. A prediction, "this will lift conversion 20%", cannot.
234- **No brand restyling.** The fonts and the palette are the project's
235  own unless they fail research on contrast, legibility, or body size.
236- **Native or existing before new.** Prefer `<dialog>`,
237  `<input type="date">`, and the project's own `components/ui/*` over a
238  new dependency.
239- **Blockers, then Majors, then Minors** on every page. The Top 5 is
240  ranked by impact across the whole site, not by page order.
241- **One-page problems stay on the page.** Only repeats go site-wide.
242- No em dashes and no "enhanc-" words in any form.
243
244## Scripts
245
246### `scripts/discover_pages.py`, project to route list
247
248```bash
249python3 scripts/discover_pages.py --repo .
250python3 scripts/discover_pages.py --self-test
251```
252
253Pure stdlib. Walks the repo, skipping `node_modules`, `.next`, `dist`,
254`build`, `out`, `coverage`, and `.git`, and prints JSON: the frameworks
255found, every page with its route and layout chain, the style files, and
256the components directory.
257
258Detects `next-app`, `next-pages`, `nuxt`, `sveltekit`, `astro`, and
259plain `html` as a last resort. Route groups are dropped, parallel and
260intercepting routes are skipped, `[id]` becomes `:id`, `[...slug]`
261becomes `*slug`, and `[[...slug]]` becomes `*slug?`.
262
263Remix and React Router file routes are not supported in v1. The script
264says so on stderr when it sees `app/routes/` and nothing else matched;
265list those pages by hand.
266
267Exit codes: `0` pages found, `1` bad path, `2` nothing found.
268
269## Common Pitfalls
270
271- **An uncited finding.** The unforgivable one. Without `[Rn]` or
272  `[Sn]` it is taste, and the report stops being worth reading.
273- **A vague change.** "Improve the hierarchy" tells an implementer
274  nothing. Name the class, the component, or the element.
275- **Reading pages before the global layer.** Do Step 2a first, or every
276  recommendation names token values the project does not have.
277- **Auditing the brand instead of the experience.** The colors are
278  theirs. Only raise them when they fail contrast or legibility.
279- **Recommending a library for a native element.** A date picker
280  dependency where `<input type="date">` works is a finding against the
281  report, not in it.
282- **Listing every nit.** Minors are capped at five per page. The rest
283  are cut, not squeezed in.
284- **Screenshotting a login redirect and calling the page audited.**
285  Mark it "not rendered, needs a session" and read the code.
286- **Overwriting yesterday's report silently.** If the file exists, ask.
287- **A prediction dressed as research.** Percentages nobody measured on
288  this project do not go in.
289
290## Verification Checklist
291
292- [ ] Every finding carries `[Rn]` or `[Sn]`, and every label resolves
293      in the Sources section.
294- [ ] Every finding names a file and a component, in existing mode.
295- [ ] Every change names a class, a component, or an element.
296- [ ] The Top 5 has five entries, ranked by impact across the site.
297- [ ] Every page section ends with a Keep line.
298- [ ] Findings on each page run Blockers, then Majors, then Minors,
299      with five Minors at most.
300- [ ] The Scope line states code only or rendered, and names the page
301      count and the framework.
302- [ ] The report path is printed in chat with the Top 5.
303- [ ] No em dashes and no "enhanc-" words.
304

1---
2name: competitor-swot
3description: "This skill should be used when the user wants competitive recon on one company or the top competitors in any category: who runs them, when they started, funding, features, pricing, gaps, and a SWOT, compared against the user's own product. It picks competitors by traffic evidence, researches each in parallel with cited sources, and produces one HTML report with a company table, a colored feature matrix, a price chart, a SWOT grid per competitor, and a SWOT for the user's product. Triggers on \"recon this site\", \"competitor analysis\", \"SWOT for the top competitors\", \"compare us to X\", \"who are our competitors\", \"competitive landscape\"."
4version: 1.0.0
5author: Xavier Collantes
6license: MIT
7platforms: [linux, macos, windows]
8metadata:
9  hermes:
10    tags: [Research, Competitive-Analysis, SWOT, Market-Research, Recon, Strategy]
11    related_skills: [business-pitch, pricing-analysis, finance-research]
12prerequisites:
13  commands: [curl, whois, dig, python3]
14---
15
16# Competitor SWOT
17
18Research one company or the top N competitors in a category, compare
19each against the user's product, and publish one report: company
20development, a feature matrix, a price chart, a SWOT per competitor,
21and a SWOT for the user's product against the whole field.
22
23## Overview
24
25The pipeline, in order:
26
27```
28inputs -> read our product -> pick competitors by traffic rank
29       -> parallel research (one worker per competitor)
30       -> reconcile and label every claim
31       -> report.html -> one screenshot check -> publish -> handoff
32```
33
34Two rules carry the whole skill:
35
36- **Every fact is sourced, and every weak fact is labeled.** A figure
37  from the company's own site is "claimed". A figure from one search
38  snippet or an unreachable page is "unverified". A bare number with
39  no source is a bug.
40- **"Not found" is not "does not have".** The feature matrix legend
41  says so, and a missing feature is only called missing when a
42  public page says it is missing.
43
44## When to Use
45
46Use for competitive recon on a single site, a head-to-head against
47one rival, or a landscape of the top N products in a category.
48
49| The user wants                          | Use instead        |
50| --------------------------------------- | ------------------ |
51| A pitch deck or investor business plan  | business-pitch     |
52| Price tracking for a product over time  | pricing-analysis   |
53| Stock or public-company financials      | finance-research   |
54
55Do not use for anything that needs logging in, signing up, or
56probing non-public endpoints. Public pages, public registries, and
57public DNS only.
58
59## Step 1: Collect the inputs
60
61Pull these from the user's message before asking anything:
62
63- **Category**, for example "grant writing platforms".
64- **Target customer**, for example "US nonprofits".
65- **Core job to be done**, the task customers buy the product for.
66- **N**, the number of competitors. Default 5. A single URL means N=1.
67- **Our product**: a repo path, a URL, or a short description.
68- **Known candidates**, if any.
69
70Ask only for what is missing and cannot be defaulted. If there is no
71"our product", run in market-only mode: skip every "vs us" part.
72
73## Step 2: Read our product as it really is
74
75If a repo is given, read its README and docs first. Describe what
76the code does today, not what the landing page claims. Note:
77
78- the core differentiator and whether competitors already sell it
79- real data versus sample or placeholder data
80- missing basics (collaboration, review, integrations, pricing)
81- the product name, then check whether a live competitor already
82  uses it (`whois <name>.com`, a quick search)
83
84## Step 3: Pick competitors by evidence
85
86Build a candidate list from search, review sites, and listicles.
87Rank the candidates with the Tranco top 1M list, a research ranking
88that averages several traffic sources:
89
90```bash
91curl -sL https://tranco-list.eu/top-1m.csv.zip -o tranco.zip
92unzip -o -q tranco.zip
93for d in example.com rival.ai other.co; do
94  r=$(grep -m1 ",$d\$" top-1m.csv | cut -d, -f1)
95  echo "$d ${r:-not-in-top-1M}"
96done | sort -k2 -n
97```
98
99Keep only products that serve the target customer for the core job.
100Drop the other side of the market, listing-only sites, and a
101different buyer, and name each exclusion with its reason. Flag ranks
102inflated by a parent company's other product.
103
104## Step 4: Research each competitor in parallel
105
106Run one worker per competitor at the same time. Give each worker
107the same brief and a short description of our product. Each returns
108a compact report with these headings:
109
1101. **Company development**: founding year, founders and CEO, HQ,
111   legal entity, funding rounds and investors (or revenue from a
112   990 or filing), headcount, acquisitions, claimed customers,
113   milestones over the last 3 years.
1142. **Product**: core features for the job, data sources and scale,
115   AI features and model if disclosed, collaboration, integrations
116   and API, onboarding, human services, recent launches.
1173. **Pricing**: public tiers, free plan or trial, demo-only gating.
1184. **Target market**.
1195. **User sentiment**: review ratings with counts, top three praises
120   and complaints.
1216. **SWOT**: 3 to 5 evidence-based bullets per quadrant.
1227. **Versus our product**: 3 things they have that we lack, 1 to 3
123   openings where we could win.
1248. **Sources**: every URL actually used.
125
126Recon commands for the site itself:
127
128```bash
129whois example.com | grep -iE 'creat|registrar:|registrant (org|country)'
130for t in A NS MX TXT; do echo "$t: $(dig +short example.com $t | tr '\n' ' ')"; done
131curl -sIL https://example.com/ | grep -iE '^(HTTP|server|x-|via|content-security)'
132curl -s "https://crt.sh/?q=example.com&output=json"      # first certificate dates
133curl -s https://example.com/robots.txt; curl -s https://example.com/sitemap.xml | grep -c ''
134```
135
136Public registries for the legal entity: Brønnøysund (Norway),
137Companies House (UK), SEC EDGAR (US public), ProPublica Nonprofit
138Explorer (US nonprofits), OpenCorporates (everywhere else).
139
140When a competitor brags about a big database, open 20 evenly spaced
141entries from its sitemap and classify them. Count what is actually
142relevant to the target customer.
143
144## Step 5: Reconcile
145
146Before writing, cross-check the workers:
147
148- Verify acquisition and funding dates against two sources.
149- Throw out figures that belong to a same-named company.
150- Keep a list of corrections to anything said earlier in the
151  conversation. They go in the handoff.
152
153## Step 6: Build the report
154
155One self-contained HTML file, `recon/<slug>/report.html`, with:
156
1571. **Lede**: 3 to 4 key takeaways and a jump nav to each competitor.
1582. **How they were picked**: traffic ranks, inclusion reasons,
159   exclusions.
1603. **Company development table**: founded, leadership, funding,
161   team, customers, direction. Our product is a highlighted row.
1624. **Feature matrix**: all competitors plus "Us". Badges:
163   - green check = full
164   - yellow tilde = partial or limited
165   - red cross = not offered, or not found in public materials
166
167   Each state has its own glyph so color is never the only signal,
168   plus screen-reader text. A note under the matrix explains every
169   partial mark.
1705. **Price chart**: yearly cost of the cheapest plan that includes
171   the key capability, bars drawn to one scale, "not public" shown
172   as a hatched empty bar.
1736. **Per competitor**: domain, one-line tagline, a key-facts strip
174   (founded, money, team, data, entry price, reviews), a 2x2 SWOT
175   color-coded by quadrant, and "They have, we don't" next to
176   "Where we can win".
1777. **Our SWOT against the field**, then a numbered "What to do first"
178   list based on what every rival has and what none of them does
179   well.
1808. **Sources**, grouped by competitor.
181
182Design: a polished, utilitarian report. Light and dark themes via
183CSS tokens on `:root`, redefined under `prefers-color-scheme: dark`
184and `[data-theme="dark"]`. Readable at 400px wide; wide tables scroll
185inside their own container. Plain, specific copy: active voice, no
186em dashes, no "enhance".
187
188## Step 7: Check once, publish, hand off
189
190Take one screenshot of the rendered file, fix what it shows, and do
191not screenshot again:
192
193```bash
194"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new \
195  --hide-scrollbars --window-size=920,4200 --screenshot=shot.png "file://$PWD/report.html"
196```
197
198Publish it as an artifact when that tool is available. Otherwise
199leave the file in place and give its path.
200
201The handoff is short: the link, 3 to 5 biggest findings, and the
202corrections list from Step 5.
203
204## Output
205
206```
207recon/<slug>/
208  report.html        the full report
209  shot.png           the one layout check
210```
211
212For N=1 recon (a single site), the same file carries one competitor
213section and a lighter layout: key facts, timeline, what it does,
214what it cannot do (tagged "stated" or "observed"), and sources.
215
216## Common Pitfalls
217
218- **Picking competitors from listicles.** Most are written by one
219  of the vendors. Rank by traffic, then filter by fit.
220- **Name collisions.** "Scout AI" or "Granted Health" funding
221  rounds attach to the wrong company in search results. Confirm the
222  domain on the source page.
223- **Trusting the homepage count.** A database of "tens of thousands"
224  can be mostly off-target entries. Sample it.
225- **Placeholder numbers.** Stat counters in raw HTML are often
226  filled in by JavaScript. Do not quote them.
227- **Traffic ranks inflated by a parent product.** Say so in the
228  picking table.
229- **Calling "not found" a missing feature.** Use the legend wording,
230  and only state absence when a page says it.
231- **Describing our product from its marketing.** Read the code and
232  docs; unbacked claims go in our weaknesses.
233- **Color-only badges.** Every state needs a glyph and screen-reader
234  text.
235- **Probing admin or API routes seen in page source.** Report that
236  they are exposed; never request them.
237- **Screenshot loops.** One look, one fix pass, publish.
238
239## Verification Checklist
240
241- [ ] Every figure has a source; company claims say "claimed", weak
242      sources say "unverified".
243- [ ] Competitor picks show traffic ranks and named exclusions.
244- [ ] Acquisition and funding dates confirmed against two sources.
245- [ ] No figure belongs to a same-named company.
246- [ ] Feature matrix covers every competitor plus "Us", with a
247      legend and a note for each partial mark.
248- [ ] Badges use distinct glyphs and screen-reader text.
249- [ ] Price chart bars share one scale and match the stated prices.
250- [ ] Each competitor has a key-facts strip, a 2x2 SWOT, and both
251      "vs us" boxes.
252- [ ] Our SWOT and a numbered "What to do first" list close the
253      report.
254- [ ] Page is readable at 400px and in both themes.
255- [ ] No em dashes and no "enhance".
256- [ ] Handoff includes the link, the top findings, and corrections.
257