@ericrisco/rsc 0.1.44 → 0.1.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/README.md +1 -1
  2. package/manifest.json +110 -86
  3. package/package.json +1 -1
  4. package/scripts/lib/domains.js +1 -1
  5. package/scripts/skill-migration-brief.md +104 -0
  6. package/skills/ab-testing/SKILL.md +9 -41
  7. package/skills/accessibility/SKILL.md +5 -7
  8. package/skills/ads/SKILL.md +9 -24
  9. package/skills/agent-eval/SKILL.md +7 -33
  10. package/skills/agent-safety/SKILL.md +7 -14
  11. package/skills/ai-media/SKILL.md +4 -20
  12. package/skills/analytics/SKILL.md +8 -30
  13. package/skills/analyze/SKILL.md +24 -59
  14. package/skills/angular/SKILL.md +12 -25
  15. package/skills/api-connector-builder/SKILL.md +10 -27
  16. package/skills/api-design/SKILL.md +7 -14
  17. package/skills/article-writing/SKILL.md +1 -18
  18. package/skills/astro/SKILL.md +36 -54
  19. package/skills/author-skill/SKILL.md +41 -74
  20. package/skills/author-skill/evals/README.md +5 -5
  21. package/skills/author-skill/evals/cases.yaml +8 -8
  22. package/skills/author-skill/references/description-recipe.md +25 -26
  23. package/skills/author-skill/references/eval-authoring.md +1 -1
  24. package/skills/author-skill/references/rsc-conventions.md +1 -1
  25. package/skills/automation-flows/SKILL.md +6 -16
  26. package/skills/automation-strategy/SKILL.md +1 -9
  27. package/skills/aws-essentials/SKILL.md +6 -23
  28. package/skills/backups/SKILL.md +1 -7
  29. package/skills/bash-scripting/SKILL.md +5 -9
  30. package/skills/bookkeeping/SKILL.md +2 -10
  31. package/skills/brand-identity/SKILL.md +18 -44
  32. package/skills/brand-voice/SKILL.md +4 -31
  33. package/skills/building-agents/SKILL.md +20 -103
  34. package/skills/business-intelligence/SKILL.md +9 -23
  35. package/skills/calendar-scheduling/SKILL.md +11 -27
  36. package/skills/case-studies/SKILL.md +3 -8
  37. package/skills/chatbot/SKILL.md +6 -23
  38. package/skills/chrome-extension/SKILL.md +2 -2
  39. package/skills/clarify/SKILL.md +31 -72
  40. package/skills/clickhouse-analytics/SKILL.md +2 -8
  41. package/skills/client-onboarding/SKILL.md +17 -19
  42. package/skills/cloudflare/SKILL.md +3 -8
  43. package/skills/code-review/SKILL.md +10 -23
  44. package/skills/codebase-onboarding/SKILL.md +2 -7
  45. package/skills/cold-outreach/SKILL.md +9 -30
  46. package/skills/community/SKILL.md +4 -31
  47. package/skills/competitor-watch/SKILL.md +20 -35
  48. package/skills/compliance/SKILL.md +10 -37
  49. package/skills/compose-multiplatform/SKILL.md +1 -1
  50. package/skills/constitution/SKILL.md +8 -35
  51. package/skills/content-engine/SKILL.md +4 -16
  52. package/skills/context-budget/SKILL.md +3 -21
  53. package/skills/continuous-learning/SKILL.md +10 -40
  54. package/skills/contracts/SKILL.md +6 -17
  55. package/skills/coolify/SKILL.md +8 -14
  56. package/skills/cost-tracking/SKILL.md +3 -11
  57. package/skills/course-builder/SKILL.md +17 -45
  58. package/skills/course-storytelling/SKILL.md +26 -94
  59. package/skills/cpp/SKILL.md +26 -71
  60. package/skills/csharp-dotnet/SKILL.md +19 -38
  61. package/skills/customer-support/SKILL.md +14 -37
  62. package/skills/dashboard/SKILL.md +6 -26
  63. package/skills/data-cleaning/SKILL.md +37 -63
  64. package/skills/data-policy/SKILL.md +8 -21
  65. package/skills/data-scraper/SKILL.md +1 -7
  66. package/skills/debug/SKILL.md +10 -49
  67. package/skills/deployment/SKILL.md +38 -101
  68. package/skills/design/SKILL.md +34 -116
  69. package/skills/fable-operator/SKILL.md +1 -4
  70. package/skills/fastapi/SKILL.md +50 -82
  71. package/skills/flutter/SKILL.md +41 -89
  72. package/skills/go/SKILL.md +57 -105
  73. package/skills/harness/SKILL.md +52 -68
  74. package/skills/implement/SKILL.md +1 -1
  75. package/skills/init/SKILL.md +152 -168
  76. package/skills/marketing/SKILL.md +30 -80
  77. package/skills/nextjs/SKILL.md +42 -116
  78. package/skills/orient/SKILL.md +25 -20
  79. package/skills/parallel/SKILL.md +9 -75
  80. package/skills/plan/SKILL.md +92 -165
  81. package/skills/postgresdb/SKILL.md +52 -72
  82. package/skills/presentations/SKILL.md +49 -87
  83. package/skills/python/SKILL.md +23 -72
  84. package/skills/react/SKILL.md +19 -67
  85. package/skills/review/SKILL.md +22 -52
  86. package/skills/rust/SKILL.md +40 -115
  87. package/skills/sdd-init/SKILL.md +9 -14
  88. package/skills/secure-coding/SKILL.md +80 -109
  89. package/skills/ship/SKILL.md +25 -55
  90. package/skills/tasks/SKILL.md +37 -61
  91. package/skills/typescript/SKILL.md +22 -55
  92. package/skills/verify/SKILL.md +8 -32
  93. package/skills/viral-score/SKILL.md +122 -0
  94. package/skills/viral-score/evals/README.md +16 -0
  95. package/skills/viral-score/evals/cases.yaml +50 -0
  96. package/skills/vue-nuxt/SKILL.md +45 -106
  97. package/skills/worktrees/SKILL.md +24 -69
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: code-review
3
- description: "Use when you have a concrete diff, branch, or GitHub PR to judge on its own merits and there is no rsc-SDD spec/plan/constitution chain to key off — the standalone, spec-less giving pass behind the executable /code-review. Triggers: 'review this PR before I merge', 'revisa este diff', 'revísame el PR', 'què està malament en aquest canvi', 'tear apart the contractor's branch', 'is this PR safe to merge', 'is this dependency bump safe', '/code-review --comment 1432', 'high-signal review of this change'. Scales coverage by effort (low/medium = fewer high-confidence findings; high/max = broader, may surface uncertain ones labelled [question]); read-only by default, posts comments only with --comment and edits only with --fix. NOT the SDD review gate keyed to 02-DOCS/wiki/sdd/ that also processes incoming comments and pushes back (that is review)."
3
+ description: "Use to judge a concrete diff, branch, or GitHub PR on its own merits with no rsc-SDD spec/plan chain to key off — the spec-less giving pass behind /code-review: only findings you can defend, one verdict, read-only unless --comment or --fix. NOT the SDD gate keyed to 02-DOCS/wiki/sdd/ that also processes incoming review comments (that is `review`)."
4
4
  tags: [code-review, pr-review, quality, correctness]
5
5
  recommends: [review, secure-coding, verify]
6
6
  origin: risco
@@ -8,9 +8,7 @@ origin: risco
8
8
 
9
9
  # Code review — standalone, spec-less diff judgment
10
10
 
11
- You are reviewing a concrete change — a `git diff`, a branch, a GitHub PR, a pasted patch — on its own merits. No rsc-SDD spec/plan/constitution chain is required and you should not pretend one exists. This is the doctrine behind the executable `/code-review` slash command: same evidence bar, written as a discipline you run by hand.
12
-
13
- > **The one-line disambiguator:** `review` needs `02-DOCS/wiki/sdd/` (spec + plan + constitution) and owns the *receiving* loop. `code-review` needs only the diff. If the user is mid-SDD and wants to process incoming comments, route to `../review/SKILL.md`. If they hand you a naked diff or an inbound third-party PR, this skill.
11
+ You are reviewing a concrete change — a `git diff`, a branch, a GitHub PR, a pasted patch — on its own merits. No rsc-SDD spec/plan/constitution chain is required and you should not pretend one exists. This is the doctrine behind the executable `/code-review` slash command: same evidence bar, written as a discipline you run by hand. If the user is mid-SDD and wants to process *incoming* comments against `02-DOCS/wiki/sdd/`, that is `../review/SKILL.md`; a naked diff or an inbound third-party PR is this skill.
14
12
 
15
13
  **The north star is signal-to-noise.** Report only findings you would stake your name on. A clean diff is `APPROVE`, not a manufactured nit. High-false-positive review gets tuned out by humans in about two weeks; the bar to aim for is the logic-error review where under 1% of findings come back marked wrong. Padding does not make you look thorough — it trains the reader to ignore you.
16
14
 
@@ -30,7 +28,7 @@ git diff --stat main...HEAD # see blast radius before reading
30
28
  # A pasted patch — read it as given
31
29
  ```
32
30
 
33
- A review with no notion of intent is a review of vibes. If no purpose is stated, **infer it from the diff and say what you assumed** ("Assuming this is meant to add idempotency to the webhook handler…") so the reader can correct a wrong premise. Then read the *whole* changed file, not just the green/red lines — the structural failure of standalone review is judging a hunk without its context and shipping generic pattern-matched suggestions.
31
+ A review with no notion of intent is a review of vibes. If no purpose is stated, **infer it from the diff and say what you assumed** ("Assuming this is meant to add idempotency to the webhook handler…") so the reader can correct a wrong premise — a silent wrong premise produces a confidently wrong review. Then read the *whole* changed file, not just the green/red lines: the structural failure of standalone review is judging a hunk without its context and shipping generic pattern-matched suggestions.
34
32
 
35
33
  ## The pass order
36
34
 
@@ -47,6 +45,8 @@ Run these in order. Passes 1–5 are correctness/safety and are blocking-eligibl
47
45
 
48
46
  Pass 4 is a **boundary** pass — trace untrusted input to its sink and flag the reachable ones. For a real STRIDE/OWASP threat model with exploitability ranking and vulnerable→fixed diffs, hand off to `../secure-coding/SKILL.md`.
49
47
 
48
+ Adjacent jobs, delegated by name: running the lint/type/test gates until they are green is `../verify/SKILL.md` (this skill judges whether green is *correct*); root-causing one confirmed failure is `../debug/SKILL.md`; cross-checking spec/plan/tasks *before* code exists is `../analyze/SKILL.md`.
49
+
50
50
  ## Confidence floor and the false-positive skip-list
51
51
 
52
52
  **The 80% rule:** if you are not at least ~80% sure a finding is real, you have two moves — trace the code until you *are* sure, or downgrade it to `[question]`. Never ship a guess dressed as a defect.
@@ -103,7 +103,7 @@ End every review with exactly one, plainly — no mushy middle:
103
103
 
104
104
  ## Effort dial
105
105
 
106
- Mirror the slash command's effort level: **low/medium** → fewer, high-confidence findings (raise the confidence floor, focus on passes 1–4). **high/max** → broader coverage; you may surface uncertain findings, but they must be labelled `[question]`, never inflated into blockers. This is *coverage vs precision* and is distinct from the harness L0..L3 accompaniment dial, which sets how much you narrate, not how rigorous you are.
106
+ Mirror the slash command's effort level: **low/medium** → fewer, high-confidence findings (raise the confidence floor, focus on passes 1–4). **high/max** → broader coverage; uncertain findings are allowed but must be labelled `[question]`, never inflated into blockers. This is *coverage vs precision*, not the harness accompaniment dial — it changes what you look at, not how much you narrate.
107
107
 
108
108
  ## Emitting comments and applying fixes
109
109
 
@@ -120,24 +120,11 @@ gh pr review 1432 --approve -b "APPROVE — correctness and contracts clean."
120
120
 
121
121
  Inline line-anchored comments go through the GitHub REST API — see `references/pr-workflow.md` for the JSON shape, fork-PR handling, and large-diff strategy. If `--fix` puts you on the default branch, **branch first**; commit or push **only when the user asks**; git authorship is **Eric** (no Claude co-author or generated footer).
122
122
 
123
- ## Anti-patterns → STOP
123
+ ## Anti-patterns
124
124
 
125
- | Rationalization | Reality |
125
+ | Failure mode | Reality |
126
126
  |---|---|
127
127
  | "It compiles and the tests pass, so it's correct." | Tests prove green, not correct. Pass 5 asks whether the tests actually exercise the new branch — green for the wrong reason is a finding. |
128
- | "I'll list everything I'd have done differently." | That is noise. Report defects and reuse wins you can defend; preference is not a finding. |
129
- | "This looks like a bug." | Looks-like is not a finding. Trace the value to a reachable sink, or file it `[question]`. |
130
- | "More findings = more thorough." | False positives get you tuned out in two weeks. Signal-to-noise is the metric; one real blocker beats ten nits. |
131
- | "No PR description, so I'll guess the intent silently." | State the intent you assumed. A wrong silent premise produces a confidently wrong review. |
128
+ | Listing everything you would have done differently. | That is noise. Report defects and reuse wins you can defend; preference is not a finding. |
132
129
  | "It's just a dependency bump, skim it." | Bumps carry supply-chain and transitive risk and behaviour changes. Check the changelog/lockfile diff, not just the version string. |
133
- | "Apply every nit to be safe." | Each unrequested edit is scope creep and a regression surface. With `--fix`, apply the agreed findings only. |
134
-
135
- ## See Also
136
-
137
- - `../review/SKILL.md` — the rsc-SDD penultimate gate keyed to `02-DOCS/wiki/sdd/`, and the *receiving* loop (process comments, push back with proof).
138
- - `../secure-coding/SKILL.md` — deep STRIDE/OWASP threat model with vulnerable→fixed diffs; the depth pass 4 defers to.
139
- - `../verify/SKILL.md` — run lint/type/test/`verify.sh` and prove green (code-review judges whether green is correct).
140
- - `../debug/SKILL.md` — root-cause one confirmed failure (code-review surveys for latent ones).
141
- - `../analyze/SKILL.md` — consistency across spec/plan/tasks *before* code exists.
142
- - `../ship/SKILL.md` — PR/merge/close after approval; consumes this skill's verdict.
143
- - Stack idiom for the change under review: `../nextjs/SKILL.md`, `../fastapi/SKILL.md`, `../go/SKILL.md`, `../typescript/SKILL.md`, `../python/SKILL.md`.
130
+ | Applying every nit "to be safe" under `--fix`. | Each unrequested edit is scope creep and a regression surface. Apply the agreed findings only. |
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: codebase-onboarding
3
- description: "Use when you land in an unfamiliar or inherited codebase and must get productive fast — map the entry points, the request/data flow, who owns the business logic, the hidden side effects (cron, webhooks, workers, listeners) and the hotspot files, before you touch anything. Triggers: 'I just cloned this repo and don't know where anything is', 'I inherited this project, map it before I change something', 'where does the business logic actually live', 'what happens behind the scenes when a request hits /checkout', 'which files are the dangerous ones nobody understands', 'acabo de heredar este repo y no sé por dónde empezar, mápamelo', 'mapea este codebase'. NOT a deep correctness/security audit of one module (that is analyze)."
3
+ description: "Use when you land in an unfamiliar or inherited codebase and must get productive fast: a breadth-first map of entry points, request flow, module ownership, hidden side effects (cron, webhooks, workers) and churn hotspots, committed as CODEBASE-MAP.md. NOT a deep audit of one module (that is `analyze`) or chasing one failure (that is `debug`)."
4
4
  tags: [onboarding, codebase, code-mapping, legacy-code, architecture, reverse-engineering, hotspots]
5
5
  recommends: [analyze, debug, decision-records, harness, init, knowledge-ops]
6
6
  origin: risco
@@ -68,7 +68,7 @@ git log --format=format: --name-only --since=12.month \
68
68
  | grep -v '^$' | sort | uniq -c | sort -nr | head -50
69
69
  ```
70
70
 
71
- The richer move is **churn × complexity**: the top-right quadrant (changes constantly *and* is hard to read) is your real danger zone (understandlegacycode.com Hotspots, accessed 2026-06-02). Escalate to that — or to a tree-sitter dependency graph — only when grep + churn is not enough; see the playbook.
71
+ The richer move is **churn × complexity**: the top-right quadrant (changes constantly *and* is hard to read) is your real danger zone (understandlegacycode.com Hotspots, accessed 2026-06-02). Escalate to that — or to a tree-sitter dependency graph — only when grep + churn is not enough: `references/recon-playbook.md` has the churn×complexity recipe (code-maat) and when codegraph PageRank / FileScopeMCP earn their setup cost.
72
72
 
73
73
  **g. Confirm hands-on.**
74
74
  Run the app, walk one end-user journey, send a real request, watch the logs. Reading alone leaves the map unverified; a single real request validates the whole trace in step c.
@@ -106,9 +106,6 @@ rg -n "queue|worker|bull|sidekiq|celery|sqs|rabbitmq|kafka|@task" -i
106
106
 
107
107
  # Env-driven branches (hidden config-conditional behavior)
108
108
  rg -n "process\.env\.|os\.environ|ENV\[|getenv"
109
-
110
- # Hotspots: churn over the last year
111
- git log --format=format: --name-only --since=12.month | grep -v '^$' | sort | uniq -c | sort -nr | head -50
112
109
  ```
113
110
 
114
111
  ## Writing & maintaining the map
@@ -129,5 +126,3 @@ git log --format=format: --name-only --since=12.month | grep -v '^$' | sort | un
129
126
  | Map lives only in chat | Dies with the session; next agent redoes it | Write & commit `CODEBASE-MAP.md` |
130
127
  | Guess instead of grep | Confident-wrong is worse than slow-right | Form the hypothesis, then `rg` to confirm or kill it |
131
128
  | Stand up a tree-sitter MCP graph on a 5-file repo | Setup costs more than the whole recon | Reserve graph tools for large monorepos; grep + churn first |
132
-
133
- See `references/recon-playbook.md` for per-ecosystem entry points and side-effect patterns, the churn×complexity recipe (code-maat), and when a tree-sitter graph (codegraph PageRank, FileScopeMCP) earns its setup cost.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: cold-outreach
3
- description: "Use when writing a cold email or DM to someone with no prior relationship, building a follow-up sequence, deciding how fast/how much to send per inbox so it stays out of spam, or rescuing outreach that reads like a template. Covers first-touch copy under a word ceiling, 4-7 step bump sequences, email-vs-LinkedIn variants, per-inbox volume and new-domain warm-up ramps, and the CAN-SPAM/GDPR opt-out footer. Triggers: 'write me a cold email', 'fix my follow-up sequence', 'my cold emails get opened but nobody replies', 'how many emails per inbox per day before I get blacklisted', 'write a LinkedIn connection note + DM', 'this email reads like a template', 'escríbeme una secuencia de cold email en frío', 'missatge en fred a LinkedIn'. NOT the SPF/DKIM/DMARC/tracking-domain setup (that is email-deliverability), NOT sourcing the prospect list (that is lead-gen), NOT what happens after a reply (that is sales-pipeline)."
3
+ description: "Use when writing a cold email or LinkedIn DM to a stranger and its cadence: first-touch copy under a word ceiling, 4-7 step bump sequences, per-inbox volume and warm-up limits, the compliant opt-out footer. NOT SPF/DKIM/DMARC setup (that is email-deliverability), NOT sourcing the list (that is lead-gen), NOT life after a reply (that is sales-pipeline)."
4
4
  tags: [cold-email, outreach, sequences, deliverability, sales]
5
5
  recommends: [lead-gen, sales-pipeline, email-deliverability, proposals, marketing]
6
6
  origin: risco
@@ -10,20 +10,7 @@ origin: risco
10
10
 
11
11
  *You write the message a stranger actually replies to, and the sending rhythm that keeps the mailbox provider delivering it. You do not set up DNS, source the list, or run the CRM.*
12
12
 
13
- This skill owns two things and only two: the **copy** of an unsolicited 1:1 touch (cold email, LinkedIn note/DM) and the **cadence** around it (step count, spacing, per-inbox volume, warm-up ramp, the compliant footer). Everything upstream and downstream belongs to a sibling — see the route table below and honor it.
14
-
15
- ## When to use / When NOT
16
-
17
- Use when:
18
-
19
- - Writing a cold email or its subject line to a recipient with no prior relationship.
20
- - Building or fixing a multi-step follow-up sequence (the "bump" cadence) — step count and spacing.
21
- - Writing a LinkedIn connection note or cold DM sequence.
22
- - Deciding daily/weekly send volume per inbox, or a new-domain warm-up ramp.
23
- - Writing the CAN-SPAM/GDPR-compliant footer and one-click opt-out line.
24
- - Rescuing a cold email that "reads like a template" or gets opens but no replies.
25
-
26
- Do NOT use when (route to the sibling that owns it):
13
+ This skill owns two things and only two: the **copy** of an unsolicited 1:1 touch (cold email, LinkedIn note/DM) and the **cadence** around it (step count, spacing, per-inbox volume, warm-up ramp, the compliant footer). Everything upstream and downstream belongs to a sibling — route by naming the owner, do not improvise their job:
27
14
 
28
15
  | The ask | Owner | Why it is not here |
29
16
  |---|---|---|
@@ -34,8 +21,6 @@ Do NOT use when (route to the sibling that owns it):
34
21
  | Inbound launch emails, nurture to an opted-in list, marketing-site copy | `marketing` (`../marketing/SKILL.md`) | Opted-in and broadcast copy is a different game from a 1:1 cold touch. |
35
22
  | Actually wire the send through Gmail/an ESP API or a scheduler | `email-connector` / `google-workspace` | This skill produces text + a plan; it does not push the send. |
36
23
 
37
- Only `marketing` exists in this catalog today, so it is the only sibling linked as a file. The rest are named by id — route by naming the owner, do not improvise their job.
38
-
39
24
  ## The reply-rate reality (calibrate before you write)
40
25
 
41
26
  Cold email is a low-yield channel by nature, and most "improve my copy" requests are really "stop fighting the math." Set expectations against the 2026 band:
@@ -110,7 +95,9 @@ The Good version names a real signal (`{{signal}}`), states one concrete outcome
110
95
 
111
96
  The first-touch body is literally lines 2→3→4 in order; line 1 becomes the subject. If the INFER line is generic, the email is generic no matter how many merge fields you add. **Test the INFER line in isolation: would it be false for a competitor in the same situation? If it is true of everyone, it is a platitude — go back to the OBSERVE step and pick a sharper fact.**
112
97
 
113
- When the user hands you only a company name and no signal, do not invent one. Ask for (or, if you have web access, look up) one of these signal classes, ranked by reply lift: a **hiring/role-change** signal > a **funding/launch/news** signal > a **tech-stack or job-description detail** > a **public number from their own site/report** > a **shared context** (mutual, group, event). A generic industry trend ("AI is changing your space") is not a signal and never clears the INFER test. Worked OBSERVE→INFER→BRIDGE→PROVE chains across six industries live in `references/hook-derivation.md`.
98
+ Two boundaries on the OBSERVE line, because both are unrecoverable once sent: keep it **professional, public and business-relevant** ("saw you're hiring 3 SREs" is relevant; "saw you were at the lake house last weekend" is surveillance), and **never invent it** — a fabricated "I loved your recent post on X" that does not exist destroys trust on contact.
99
+
100
+ When the user hands you only a company name and no signal, do not invent one. Ask for (or, if you have web access, look up) one of these signal classes, ranked by reply lift: a **hiring/role-change** signal > a **funding/launch/news** signal > a **tech-stack or job-description detail** > a **public number from their own site/report** > a **shared context** (mutual, group, event). A generic industry trend ("AI is changing your space") is not a signal and never clears the INFER test. If no true signal exists at all, that is a `lead-gen` targeting gap, not a copy task. Worked OBSERVE→INFER→BRIDGE→PROVE chains across six industries live in `references/hook-derivation.md`.
114
101
 
115
102
  ## The sequence — decision table
116
103
 
@@ -144,7 +131,9 @@ Rules that make the table work:
144
131
 
145
132
  *(LinkedIn figures: Skylead / Kondo / Expandi 2025-2026 guides, accessed 2026-06-02.)*
146
133
 
147
- On LinkedIn the connection note must **not** pitch — earn the connection on a real signal, then make the ask in the first DM after they accept. Skeletons for both channels live in `references/templates.md`.
134
+ On LinkedIn the connection note must **not** pitch — earn the connection on a real signal, then make the ask in the first DM after they accept.
135
+
136
+ Reusable skeletons for both channels — first-touch + 4-step bump, with every variable slot (`{{signal}}`, `{{outcome}}`, `{{proof}}`) marked — live in `references/templates.md`. Start from a skeleton, then fill every slot with a *real* value before sending. An unfilled slot is a defect, not a placeholder to ship.
148
137
 
149
138
  ## Sending cadence & deliverability guardrails
150
139
 
@@ -179,12 +168,6 @@ If the user asks you to *configure* the `List-Unsubscribe` header, SPF, or DKIM,
179
168
 
180
169
  EU enforcement varies — UK ICO and France CNIL are permissive for B2B; Germany and Poland are stricter (Poland often requires prior consent). When the recipient is in the EU, write the footer for the strictest plausible jurisdiction. The full footer wording, the LIA checklist, and the CASL/Australia matrix → `references/compliance-footer.md`.
181
170
 
182
- ## Personalization without creepiness
183
-
184
- - **One real signal, surfaced plainly.** "Saw you're hiring 3 SREs" is relevant; "Saw you were at the lake house last weekend" is surveillance. Stay on professional, public, business-relevant signals. Then run it through the four-line bridge above — a relevant signal with a generic INFER line still reads like a template.
185
- - **Do not fake personalization with spintax.** Rotating "{Hi|Hey|Hello}" or `{{first_name}}`-only mail-merge is not personalization — it is a template wearing a name tag, and recipients can smell it. If the only variable is the name, the email is generic; add a real `{{signal}}` or do not send.
186
- - **Never invent the signal.** A fabricated "I loved your recent post on X" that does not exist destroys trust on contact. If you cannot find a true signal, that is a `lead-gen` targeting gap, not a copy task.
187
-
188
171
  ## Anti-patterns
189
172
 
190
173
  | Anti-pattern | Why it fails | Do instead |
@@ -193,14 +176,10 @@ EU enforcement varies — UK ICO and France CNIL are permissive for B2B; Germany
193
176
  | Pitch in sentence one | No earned relevance; reads like a billboard | Lead with the observed signal, earn the ask |
194
177
  | Two CTAs ("call OR I'll send a guide") | Splits the decision; lowers reply rate | One binary yes/no ask per email |
195
178
  | "Just following up" / "circling back" with no new angle | Adds noise, not value; trains them to ignore you | Each step adds one new angle or it is deleted |
196
- | Name-only mail merge as "personalization" | Recipients see the template underneath | One true `{{signal}}` per first touch or do not send |
179
+ | Name-only mail merge or spintax (`{Hi\|Hey}`) as "personalization" | Recipients see the template underneath | One true `{{signal}}` per first touch or do not send |
197
180
  | No opt-out / no postal address | CAN-SPAM/GDPR violation; complaint-rate spike | Always append the compliant footer |
198
181
  | Subject like "Quick question!!" or "FREE" | Clickbait + spam-trigger words land you in spam | ≤6 plain words that read like a coworker wrote them |
199
182
  | Padding to 7 steps for completeness | Replies past step 5 are thin; you just annoy | Stop at the breakup unless a real new trigger appears |
200
183
  | "I hope this email finds you well" opener | The classic AI/template tell; wastes the first line | Open on the signal — your first 6 words are the hook |
201
184
 
202
- ## Templates
203
-
204
- Reusable skeletons — first-touch + 4-step bump for email and LinkedIn, with every variable slot (`{{signal}}`, `{{outcome}}`, `{{proof}}`) marked — live in `references/templates.md`. Start from a skeleton, then fill every slot with a *real* value before sending. An unfilled slot is a defect, not a placeholder to ship.
205
-
206
185
  To self-check a drafted email or sequence file, run `scripts/verify.sh path/to/draft.md` — it flags missing opt-out, multiple CTAs, over-ceiling word count, and spam/AI-tell phrases (read-only).
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: community
3
- description: "Use when building or running a persistent two-way community space — Discord, Telegram, or Circle — and you need structure, onboarding, moderation, rituals, growth, or health metrics; covers picking the platform, standing up channels/roles/spaces, the rules/verification gate, the 3-layer moderation stack, an operating-rhythm of rituals, lurker-to-contributor growth loops, and the few metrics that prove it is alive. Triggers: 'set up our Discord server', 'our community is a graveyard / dead chat', 'we keep getting spam raids and scam DMs', 'Discord vs Telegram vs Circle', 'design community rituals / weekly cadence', 'how do I get lurkers to post', 'community onboarding flow', 'community health metrics', 'monta la comunitat de Discord', 'la comunidad está muerta, nadie escribe'. NOT customer churn-prevention for a paid product (that is retention), NOT one-to-many broadcast email (that is newsletter), and NOT running a single live event (that is webinar)."
3
+ description: "Use when building or running a persistent two-way community space — Discord, Telegram, Circle: platform choice, structure, onboarding, native→bot→human moderation, rituals, growth loops, health metrics. NOT churn of paying product customers (that is `retention`), NOT broadcast email (that is `newsletter`), NOT one live event (that is `webinar`)."
4
4
  tags: [community, discord, telegram, moderation, growth, rituals]
5
5
  recommends: [retention, newsletter, social-publisher, brand-voice, whatsapp-telegram, webinar]
6
6
  profiles: []
@@ -11,15 +11,6 @@ origin: risco
11
11
 
12
12
  Run the community like a **product with a job**, not a vanity chat room. The space — a Discord server, a Telegram group+channel, a Circle — is the product. **Onboarding is activation, rituals are the feature, moderation is reliability, and one north-star metric tied to your purpose is the only number that matters.** A room with 5,000 silent members is a failed product, not a big one. Design the system around the conversation, not the conversation itself.
13
13
 
14
- ## When to use
15
-
16
- - Standing up a new Discord / Telegram / Circle from zero: structure, roles, onboarding, rules.
17
- - A community exists but is a graveyard — lurkers only, no rhythm, nobody posts — needs rituals + re-activation.
18
- - Moderation is on fire: spam waves, raids, scam DMs, bans applied by mood, no incident process.
19
- - Choosing between Discord vs Telegram vs Circle for a given audience, purpose, and monetization model.
20
- - Designing a growth loop that compounds (referrals, intro rituals, partner cross-posts) instead of buying dead members.
21
- - Defining community health metrics and targets and instrumenting the few that prove the thing is alive.
22
-
23
14
  ## When NOT to use — route instead
24
15
 
25
16
  | The ask | Route to |
@@ -32,9 +23,9 @@ Run the community like a **product with a job**, not a vanity chat room. The spa
32
23
  | Actually code or host the Discord/Telegram bot (gateway, slash handlers) | `whatsapp-telegram`, `automation-flows` |
33
24
  | Define the voice/name/tone the community speaks in | `../brand-voice/SKILL.md` |
34
25
 
35
- You own the **persistent, two-way space and its ongoing operating rhythm.** The boundary that bites most: `retention` keeps *buyers of a product* from churning; you keep *members of a shared space* active and contributing. They rhyme (cohorts, re-activation) but the subject differs — a SaaS seat vs a Discord membership. When a near-miss is really "send a broadcast," it is `newsletter`/`social-publisher`; when it is "stop churn of buyers," it is `retention`; when it is "run an event," it is `webinar`.
26
+ You own the **persistent, two-way space and its ongoing operating rhythm.** The boundary that bites most: `retention` keeps *buyers of a product* from churning; you keep *members of a shared space* active and contributing. They rhyme (cohorts, re-activation) but the subject differs — a SaaS seat vs a Discord membership.
36
27
 
37
- ## Step 0 — Purpose & north-star gate (hard rule)
28
+ ## Step 0 — Purpose & north-star gate
38
29
 
39
30
  **Do not design a single channel until you have (a) a one-line purpose and (b) one business metric tied to it.** Why: a community without a job becomes a dead chat — there is no signal to design toward, so you sprawl channels and beg for activity. This is the most common cause of graveyards.
40
31
 
@@ -191,7 +182,7 @@ Then validate it:
191
182
  scripts/verify.sh path/to/moderation-config.yaml
192
183
  ```
193
184
 
194
- `verify.sh` checks the required keys exist, that `north_star_metric` is non-empty, that all three moderation layers are declared, and that at least one ritual has a cadence — it catches the most common defect (a "plan" with no purpose, no mod layers, or no rhythm).
185
+ `verify.sh` checks the required keys exist, that `north_star_metric` is non-empty, that all three moderation layers are declared, and that at least one ritual has a cadence — it catches the most common defect (a "plan" with no purpose, no mod layers, or no rhythm). **Do not go live until it passes and the north-star plus at least one health metric (TTFR or DAU/MAU) are instrumented.**
195
186
 
196
187
  ## Anti-patterns
197
188
 
@@ -205,21 +196,3 @@ scripts/verify.sh path/to/moderation-config.yaml
205
196
  | Treating 90% lurkers as permanent | Leaves activation on the table | 90-9-1 is a range; move lurkers up a tier |
206
197
  | Monetizing on Circle before activation works | Charging for a dead room churns instantly | Prove rhythm + retention, then gate/monetize |
207
198
  | Broadcasting in a two-way space | Wrong tool; kills conversation | One-to-many → `../newsletter/SKILL.md` / `../social-publisher/SKILL.md` |
208
-
209
- ## Launch-readiness checklist
210
-
211
- Gate before "go live":
212
-
213
- - [ ] Purpose written in one line **and** one north-star business metric chosen (Step 0).
214
- - [ ] Platform chosen by decision rule, not vibes.
215
- - [ ] ≤ ~6 channels/spaces, each justified by the purpose.
216
- - [ ] Onboarding path wired: role-on-join → rules gate → prompted intro → where-to-ask.
217
- - [ ] All 3 moderation layers configured (native + bot + human) sized to expected scale.
218
- - [ ] ≥ 1 ritual scheduled with an explicit cadence.
219
- - [ ] North-star + ≥ 1 health metric (TTFR or DAU/MAU) instrumented.
220
- - [ ] `community-plan.md` + `moderation-config.yaml` emitted and `verify.sh` passes.
221
-
222
- ## References
223
-
224
- - `references/platform-playbooks.md` — per-platform setup depth: Discord (AutoMod filters, verification levels, Rules/Membership Screening, Onboarding, bots by size), Telegram (group+channel hybrid, native anti-spam >200, slow-mode, CAPTCHA bots), Circle (Spaces, 2026 plan ladder + fees, monetization gating).
225
- - `references/metrics-and-rituals.md` — metric definitions + benchmarks (DAU/WAU/MAU stickiness, cohort retention, TTFR, answered rate, returning-member ratio, the business-metric menu), the 90-9-1 reality, and a ritual template library + sample weekly calendar.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: competitor-watch
3
- description: "Use when you keep a named set of rivals under continuous, dated observation — tracking their pricing, features, positioning, and changelog over time, turning page diffs into a maintained tracker plus a classified change log on a cadence. Use when asked what moved at a competitor this month, whether a rival changed price or shipped something, or for a feature matrix kept current rather than written once. Triggers: 'set up competitor monitoring', 'watch their pricing page', 'did [rival] reposition or launch anything', 'what moved at [competitor] this month', 'keep this comparison matrix updated', 'track how their positioning shifted over 6 months', 'monitoritza els competidors i avisa-m quan canviïn de preu', 'vigila los precios de la competencia'. NOT sizing the market or producing the competitor list (that is market-research), NOT setting our own price (that is pricing), NOT building the sales battlecard (that is sales-pipeline)."
3
+ description: "Use when an already-named set of rivals is watched on a cadence — pricing, features, positioning and changelog diffed into a maintained tracker plus an append-only, classified change log. NOT sizing the market or choosing who the rivals are (that is `market-research`), NOT one-off page extraction (that is `data-scraper`)."
4
4
  tags: [competitive-intelligence, monitoring, pricing-tracking, feature-tracking, marketing-ops]
5
5
  recommends: [market-research, pricing, sales-pipeline, brand-voice, data-scraper, automation-flows, seo-geo]
6
6
  origin: risco
@@ -11,33 +11,17 @@ origin: risco
11
11
  You run a **standing watch**, not a one-shot study. You take an *already-named* set of
12
12
  rivals and keep them under dated observation along four axes — positioning, pricing,
13
13
  features, and change-over-time. The deliverable is not a snapshot of the market; it is the
14
- **time series** of what each rival moved, when, and what you do about it.
15
-
16
- Three hard stops up front, so you don't drift into a neighbour's job:
17
-
18
- - You do **not** size the market or invent the competitor list — that is `../market-research/SKILL.md`.
19
- - You do **not** decide *our* price, packaging, or tiers — that is `../pricing/SKILL.md`.
20
- - You do **not** build the sales battlecard / "why we win" — that is `../sales-pipeline/SKILL.md`.
21
-
22
- The near-miss that catches people is `market-research`: it answers *"what is the market and
23
- who is in it"* once and often **produces the list you watch**. You are the downstream loop
24
- that watches that list forever. The other near-miss is `../data-scraper/SKILL.md`: it owns
25
- the generic mechanics of pulling data off a page on demand; you *use* change detection as a
26
- means, but your identity is the maintained tracker + classified change log + cadence. "Extract
27
- this one table once" → data-scraper. "Keep watching these five companies" → you.
28
-
29
- ## The loop is the product
30
-
31
- Competitive intelligence is a **repeating cycle**, not a report you write and file. The
32
- taught cycle runs **Orient → Gather → Analyze → Report → Act**, then loops with a fresh
33
- orientation informed by the last pass (competitiveintelligencealliance.io, accessed 2026-06-02).
34
-
35
- - **The output is a re-run tracker, not a one-time document.** *Why:* a market changes
36
- the week after you "finish" the study; a snapshot is stale on arrival.
37
- - **Every pass appends to a change log, it does not overwrite the last.** *Why:* the value
38
- is the delta over time — "Pro tier went \$49→\$59 in May" — not the current cell alone.
39
- - **Watch the vital few, not everyone.** Pick the 3–7 rivals that move your roadmap. *Why:*
40
- watching 30 companies produces noise nobody reads; depth on the few beats breadth on the many.
14
+ **time series** of what each rival moved, when, and what you do about it. Competitive
15
+ intelligence is a **repeating cycle**, not a report you write and file: the taught cycle runs
16
+ **Orient → Gather → Analyze → Report → Act**, then loops with a fresh orientation informed by
17
+ the last pass (competitiveintelligencealliance.io, accessed 2026-06-02).
18
+
19
+ Two near-misses decide the routing (the rest are in **Handoffs**, below). `../market-research/SKILL.md`
20
+ answers *"what is the market and who is in it"* once, and often **produces the list you watch** —
21
+ you are the downstream loop that watches that list forever. `../data-scraper/SKILL.md` owns the
22
+ generic mechanics of pulling data off a page on demand; you *use* change detection as a means, but
23
+ your identity is the maintained tracker + classified change log + cadence. "Extract this one table
24
+ once" → data-scraper. "Keep watching these five companies" → you.
41
25
 
42
26
  ## Ethics gate — runs FIRST, before any capture
43
27
 
@@ -61,8 +45,9 @@ If a request needs any of those, **refuse and reframe to the legal equivalent**:
61
45
  1. **Get the competitor list.** If there is none, or it's unvalidated guesswork → STOP and
62
46
  route to `../market-research/SKILL.md`. *Why:* watching the wrong rivals forever is worse
63
47
  than not watching. You are not the one who decides who the competitors are.
64
- 2. **Pick the watch-axes** from the canonical surface list (below). Don't watch everything —
65
- watch what changes your decisions.
48
+ 2. **Pick the vital few, then the watch-axes.** The 3–7 rivals that move your roadmap, and only
49
+ the surfaces (below) that change your decisions. *Why:* watching 30 companies on every axis
50
+ produces noise nobody reads; depth on the few beats breadth on the many.
66
51
  3. **Persist the tracker of record** under `02-DOCS/wiki/competitors/` (one profile per rival
67
52
  + a shared change log); keep raw captures under `02-DOCS/raw/competitors/`. *Why:* the
68
53
  tracker is a maintained artifact, not a chat answer — it has to live somewhere re-runnable.
@@ -191,8 +176,8 @@ recommend a SaaS. Full docker-compose + per-axis watch recipe is in `references/
191
176
  ## Verify
192
177
 
193
178
  After you emit a tracker / change log / config, run `scripts/verify.sh` against your project
194
- docs. It lints (read-only): required tracker columns present; **every pricing/feature row has
195
- a non-empty `source_url` and `date`** (the anti-invention guard); change-log `axis` and
196
- `materiality` are in the allowed sets and every row has a `url` + `date`; and it **warns** when
197
- a monitoring-config entry pairs a slow axis with a sub-15-min cadence or a pricing axis with a
198
- slower-than-daily cadence. It exits 0 on an empty/clean target — no false failures.
179
+ docs. Read-only lint: required tracker columns present; **every pricing/feature row has a
180
+ non-empty `source_url` and `date`** (the anti-invention guard); change-log `axis` and
181
+ `materiality` in the allowed sets, with a `url` + `date` on every row; and a **warning** when a
182
+ monitoring-config entry pairs a slow axis with a sub-15-min cadence, or pricing with a
183
+ slower-than-daily one. It exits 0 on an empty/clean target — no false failures.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: compliance
3
- description: "Use when a business needs to know which regulatory frameworks actually bind it and how to keep the program true between audits — scoping SOC 2 / ISO 27001 / HIPAA / PCI DSS / EU AI Act / DORA / NIS2, building a control register with owners and evidence, or standing up a recurring compliance cadence. Triggers: 'what compliance do we need for a fintech', 'build a SOC 2 readiness checklist', 'map our controls — who owns what', 'we have an audit in 90 days, set up the prep rhythm', 'does the EU AI Act apply to us and what's the deadline', 'set up a continuous-compliance calendar so we stop scrambling', '¿qué compliance necesitamos para una app de salud con datos médicos?', 'muntar el checklist de SOC 2'. NOT drafting the privacy policy, ROPA, or DPA text (that is gdpr-privacy), NOT writing Terms of Service (that is terms-conditions), NOT hardening the code itself (that is secure-coding)."
3
+ description: "Use when scoping which regulatory frameworks bind a business — SOC 2, ISO 27001, HIPAA, PCI DSS, EU AI Act, DORA, NIS2 — building a control register with owners and evidence, or standing up the cadence that keeps it audit-ready. NOT drafting privacy-policy/ROPA/DPA or ToS text (that is gdpr-privacy, terms-conditions), NOT hardening code (that is secure-coding)."
4
4
  tags: [compliance, soc2, iso27001, audit-readiness, controls, governance]
5
5
  recommends: [gdpr-privacy, terms-conditions, data-policy, contracts, secure-coding]
6
6
  origin: risco
@@ -8,28 +8,21 @@ origin: risco
8
8
 
9
9
  # Compliance — scope the frameworks, build the register, run the rhythm
10
10
 
11
- You turn a vague "we need to be compliant" into two artifacts that survive an
12
- audit:
13
-
14
- 1. **A sector regulatory checklist** — the specific frameworks that actually
15
- bind *this* business, decomposed into named controls, each with an owner and
16
- an evidence source.
17
- 2. **A compliance operating rhythm** — the recurring calendar (control reviews,
18
- evidence refresh, access recerts, vendor reassessments, audit prep) that
19
- keeps the program true between audits instead of scrambling once a year.
11
+ You turn a vague "we need to be compliant" into artifacts that survive an audit:
12
+ a scoped framework list with current deadlines, a **control register** (one row
13
+ per control, tagged to every framework it satisfies, each with an owner and an
14
+ evidence source), a **cadence calendar** of the recurring work that keeps the
15
+ program true between audits instead of scrambling once a year, and an
16
+ evidence-source catalog.
20
17
 
21
18
  Your job is **scoping and orchestration, not legal opinion**. You map the
22
19
  business to the frameworks, build the register, assign owners and cadences, and
23
20
  stand up the rhythm. You do not give legal advice; flag where a licensed
24
21
  specialist or auditor must sign off.
25
22
 
26
- ## What you produce — and what you refuse
27
-
28
- **Produce:** a scoped framework list with current deadlines, a control register
29
- (one row per control, tagged to every framework it satisfies), a cadence
30
- calendar, and an evidence-source catalog.
31
-
32
- **Refuse and route** — these are owned by siblings, not by you:
23
+ **Route out** — these are owned by siblings, not by you. You *reference* the
24
+ resulting documents as evidence sources in the register; you do not write them
25
+ here.
33
26
 
34
27
  - Privacy notice, ROPA, DSAR flow, consent banner → `../gdpr-privacy/SKILL.md`.
35
28
  - Terms of Service, EULA, acceptable-use → `../terms-conditions/SKILL.md`.
@@ -38,9 +31,6 @@ calendar, and an evidence-source catalog.
38
31
  - Hardening the code (authn, secrets, injection, headers) →
39
32
  `../secure-coding/SKILL.md`.
40
33
 
41
- You *reference* these documents as evidence sources in the register; you do not
42
- write them here.
43
-
44
34
  ## Step 1 — Scope to the frameworks that actually bind
45
35
 
46
36
  Do not copy a framework because a competitor has it. Map business attributes to
@@ -159,26 +149,9 @@ before the auditor arrives.
159
149
  | Drafting the privacy policy / DPA here | That's legal-document substance, a different skill's lane | Route to `../gdpr-privacy/SKILL.md` / `../contracts/SKILL.md` |
160
150
  | Giving a legal opinion | You scope and orchestrate; you are not counsel | Flag where a licensed specialist or auditor must sign off |
161
151
 
162
- ## References
163
-
164
- - `references/frameworks.md` — per-framework cheat sheets with current dates and
165
- control counts: SOC 2 (5 TSC, Type I/II), ISO 27001:2022, EU AI Act phase
166
- dates + fines, PCI DSS 4.0.1, HIPAA (+ 2024 NPRM forthcoming), DORA, NIS2,
167
- GDPR as a control source.
168
- - `references/operating-rhythm.md` — control-register schema, the full cadence
169
- calendar, the evidence-source catalog, and the audit-prep runbook.
170
-
171
152
  ## Verify
172
153
 
173
154
  `scripts/verify.sh <register>` lints a control register (Markdown table or CSV):
174
155
  it checks the required columns exist and that no row is missing an owner,
175
156
  evidence, or cadence — the cardinal sin of checklist theater. Read-only, exits 0
176
157
  on a clean or empty register.
177
-
178
- ## See also
179
-
180
- - `../gdpr-privacy/SKILL.md` — privacy notice, ROPA, DSAR, consent.
181
- - `../terms-conditions/SKILL.md` — ToS, EULA, acceptable-use.
182
- - `../data-policy/SKILL.md` — internal retention/classification policy text.
183
- - `../contracts/SKILL.md` — MSA / DPA / NDA drafting and review.
184
- - `../secure-coding/SKILL.md` — code-level hardening that produces your evidence.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: compose-multiplatform
3
- description: "Use when building shared UI across Android, iOS, and desktop from one Kotlin codebase with Compose Multiplatform — shared commonMain @Composables, expect/actual for platform divergence, native interop, multiplatform ViewModel/navigation/Koin. Triggers: 'share one Compose UI across Android and iOS', 'my expect has no actual and the build fails', 'where does this code go — commonMain or iosMain', 'embed a SwiftUI/UIKit view inside shared Compose with UIKitView', 'host shared Compose in a SwiftUI app', 'add a desktop target and package it', 'compartir la UI entre Android i iOS amb Kotlin', 'una sola UI para Android, iOS y escritorio'. NOT a single-platform native build (that is kotlin-android / swift-ios), and NOT Dart/Flutter cross-platform UI (that is flutter)."
3
+ description: "Use when building one shared Compose UI in Kotlin across Android, iOS, and desktop — commonMain @Composables, expect/actual, source-set placement, native interop, multiplatform ViewModel/navigation/Koin. NOT a single-platform native build (that is kotlin-android / swift-ios), and NOT Dart/Flutter cross-platform UI (that is flutter)."
4
4
  tags: [kotlin, kmp, compose-multiplatform, cross-platform, shared-ui, expect-actual, ios, android]
5
5
  recommends: [kotlin-android, swift-ios, flutter, tauri]
6
6
  origin: risco
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: constitution
3
- description: "Use when capturing or revising a project's non-negotiable principles — its stack canon, quality bars, naming/structure conventions, branching/commit rules, testing thresholds, security and accessibility floors, the things every later phase must obey. This is the FIRST rsc-sdd phase, run once per project (then amended). Writes/updates 02-DOCS/wiki/sdd/constitution.md and links it from the root CLAUDE.md Knowledge map; reconciles with conventions the harness already holds under 02-DOCS/wiki/stack/*. Triggers: 'set the project principles', 'define our engineering standards', 'establecer las reglas del proyecto', 'project constitution', 'what are our non-negotiables', 'lock the stack canon', 'quality bar', 'coding standards doc', 'amend the constitution', 'ratify principle', 'definition of done for the repo'. NOT a feature spec (that's specify) and NOT an implementation plan (that's plan)."
3
+ description: "Use when setting or amending a project's non-negotiables — stack canon, quality bars, conventions, security/a11y floors — as numbered, testable rules later phases obey. First rsc-sdd phase; writes 02-DOCS/wiki/sdd/constitution.md. NOT a feature spec (that is `specify`), NOT the technical plan (that is `plan`), NOT the wiki itself (that is `harness`)."
4
4
  tags: [sdd, constitution, principles]
5
5
  recommends: [specify]
6
6
  profiles: [core, full]
@@ -13,7 +13,7 @@ origin: risco
13
13
 
14
14
  A constitution is small, durable, and enforceable. It is **not** a wiki of everything you know about the project (that is what `02-DOCS/wiki/` already is, run by the `harness`). It is the short list of principles that, if violated, mean the work is wrong regardless of whether it runs. If a rule here cannot be checked or pointed at later, it does not belong here — move it to the stack wiki and link it.
15
15
 
16
- This skill produces `02-DOCS/wiki/sdd/constitution.md` and one Knowledge-map row. The constitution is one of the few **read-first** pointer entries kept directly in the root `CLAUDE.md` `## Knowledge map` (everything else lives in `02-DOCS/wiki/index.md`, the full Knowledge map that root `CLAUDE.md` points to). It reconciles with — never duplicates — the stack conventions the harness keeps under `02-DOCS/wiki/stack/*`.
16
+ Not this phase: *what to build* → `../specify/SKILL.md`; the technical approach for one feature → `../plan/SKILL.md`; setting up `01-TOOLS/` + `02-DOCS/` or capturing general project knowledge → `harness`; concrete stack mechanics (*how* to configure Ruff, pytest, Tailwind tokens) → the relevant stack skill (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`, `../design/SKILL.md`, `../secure-coding/SKILL.md`). The constitution *names* the bar; the stack skill *enforces* it.
17
17
 
18
18
  ## Model tier — `heavy` (opt-in routing)
19
19
 
@@ -21,7 +21,7 @@ This phase's default model tier is **`heavy`** — it sets the project's non-neg
21
21
 
22
22
  ## Honor the accompaniment dial first
23
23
 
24
- Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` and match its `technical_level` and `accompaniment_level`. The constitution interview adapts:
24
+ Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` and match its `technical_level` and `accompaniment_level`. No profile yet → default to non-technical and ask the two gauging questions, or point the user at `init`; never assume fluency. The constitution interview adapts:
25
25
 
26
26
  | Level | How this skill behaves |
27
27
  |-------|------------------------|
@@ -30,24 +30,6 @@ Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` and match it
30
30
  | L2 — explica decisiones | Justify each principle as you propose it; surface trade-offs where a rule constrains the team. |
31
31
  | L3 — acompañamiento total | Explain what a constitution is and why each section matters, one kind question at a time, before writing anything. Non-technical framing. |
32
32
 
33
- If there is no profile yet, default to non-technical and ask the two gauging questions (technical level, accompaniment level) before proceeding — or point the user at `init`. Never assume fluency.
34
-
35
- ## When to use / when NOT to use
36
-
37
- Use when:
38
-
39
- - A project is being set up and needs its principles fixed before features are specified.
40
- - The team keeps relitigating the same decisions (test coverage, formatting, branch naming) and wants them ratified once.
41
- - An existing repo has implicit conventions that should be made explicit and enforceable.
42
- - A principle needs to change — amend the constitution (see the amendment protocol).
43
-
44
- Do NOT use when (route instead):
45
-
46
- - The user wants to describe *what to build* → `../specify/SKILL.md` (a feature spec, not project-wide law).
47
- - The user wants the *technical approach* for a feature → `../plan/SKILL.md`.
48
- - The user wants to set up `01-TOOLS/` + `02-DOCS/` or capture general project knowledge → `harness` (the constitution lives inside that wiki, but the wiki itself is the harness's job).
49
- - The user wants concrete stack mechanics (e.g. *how* to configure Ruff, pytest, Tailwind tokens) → the relevant stack skill (`fastapi`, `nextjs`, `go`, `postgresdb`, `flutter`, `design`). The constitution *names* the bar; the stack skill *enforces* it.
50
-
51
33
  ## Reconcile before you write (do not duplicate the stack wiki)
52
34
 
53
35
  The harness may already hold real conventions under `02-DOCS/wiki/stack/*` (e.g. `nextjs.md`, `fastapi.md`, `postgresdb.md`). The constitution does not copy them — it **ratifies the principle and links the detail**. Run this reconciliation pass first:
@@ -64,7 +46,7 @@ The rule of thumb: the constitution says *"every endpoint is typed and tested to
64
46
  Every principle in the constitution is one numbered, testable statement. A vague aspiration is not a principle.
65
47
 
66
48
  - **Imperative and specific.** "Code is formatted with the repo's formatter on every commit" — not "we value clean code".
67
- - **Checkable.** There must be a way for `analyze` and `verify` to tell whether it held. Prefer a number, a command, or a named artifact.
49
+ - **Checkable.** There must be a way for `../analyze/SKILL.md` and `verify` to tell whether it held. Prefer a number, a command, or a named artifact.
68
50
  - **Owned.** If enforcement lives in a stack skill or a script, link it.
69
51
  - **Falsifiable in review.** A reviewer can point at a diff and say "this violates principle 4".
70
52
 
@@ -116,10 +98,10 @@ The constitution is versioned so `analyze` and `review` can cite "constitution v
116
98
  - **Ratification.** A new or amended constitution is shown to the user and ratified explicitly before it takes effect. At L0, "ratify" is a quick yes; at L3, walk each change.
117
99
  - **Downstream notice.** When a principle changes mid-project, flag that existing specs/plans may now be inconsistent — `analyze` will catch the drift on the next run.
118
100
 
119
- ## Anti-patterns → STOP
101
+ ## Anti-patterns
120
102
 
121
- | Rationalization | Reality / fix |
122
- |-----------------|---------------|
103
+ | Anti-pattern | Why it fails / fix |
104
+ |--------------|--------------------|
123
105
  | "I'll write a thorough constitution covering everything about the project." | That's the wiki, not the constitution. Keep only enforceable non-negotiables; link the rest. |
124
106
  | "This stack detail is important, I'll paste the lint config in here." | No. Ratify the principle, link `wiki/stack/*` for the mechanic. The constitution names the bar; the stack skill enforces it. |
125
107
  | "Two stack articles disagree — I'll just pick the stricter one." | Contradictions are findings. Surface them; the user resolves. |
@@ -137,7 +119,7 @@ The constitution is versioned so `analyze` and `review` can cite "constitution v
137
119
  - [ ] The Definition-of-Done checklist is present (what `verify` runs against).
138
120
  - [ ] Fixed principles included: human git authorship + decisions logged.
139
121
  - [ ] `02-DOCS/wiki/sdd/constitution.md` written with version + ratified date + amendment log.
140
- - [ ] Root `CLAUDE.md` `## Knowledge map` pointer has the read-first row for the constitution (it is one of the few entries kept in root `CLAUDE.md`; the full index lives in `02-DOCS/wiki/index.md`). Additive only — never delete sections.
122
+ - [ ] Root `CLAUDE.md` `## Knowledge map` pointer has the read-first row for the constitution.
141
123
  - [ ] The constitution was shown to the user and explicitly ratified.
142
124
 
143
125
  ## Project grounding (02-DOCS + CLAUDE.md)
@@ -153,12 +135,3 @@ Every later rsc-sdd phase reads this file before it works. The harness maintains
153
135
  ## Next in the chain
154
136
 
155
137
  The constitution is the guardrail; now describe what to build. Hand off to **`../specify/SKILL.md`** — turn a fuzzy intent into a spec (what & why, no implementation), grounded in these principles. The full chain: **constitution → specify → clarify → plan → tasks → analyze → implement → verify → review → ship** (with `debug`, `worktrees`, `parallel` callable on demand). The dispatcher is `../sdd/SKILL.md`.
156
-
157
- ## See Also
158
-
159
- - `../sdd/SKILL.md` — the rsc-sdd dispatcher: the method, the phase map, the invoke rule.
160
- - `../specify/SKILL.md` — the next phase: intent → spec.
161
- - `../analyze/SKILL.md` — the consistency gate that checks specs/plans against this constitution.
162
- - `harness` — owns `02-DOCS/wiki/` (including `wiki/stack/*` and the full Knowledge map at `02-DOCS/wiki/index.md` this skill reconciles with; the constitution's read-first row stays in the root `CLAUDE.md` pointer).
163
- - Stack skills the constitution *names but does not duplicate*: `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`, `../design/SKILL.md`, `../secure-coding/SKILL.md`.
164
- - References: `references/constitution-template.md`.