@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.
- package/README.md +1 -1
- package/manifest.json +110 -86
- package/package.json +1 -1
- package/scripts/lib/domains.js +1 -1
- package/scripts/skill-migration-brief.md +104 -0
- package/skills/ab-testing/SKILL.md +9 -41
- package/skills/accessibility/SKILL.md +5 -7
- package/skills/ads/SKILL.md +9 -24
- package/skills/agent-eval/SKILL.md +7 -33
- package/skills/agent-safety/SKILL.md +7 -14
- package/skills/ai-media/SKILL.md +4 -20
- package/skills/analytics/SKILL.md +8 -30
- package/skills/analyze/SKILL.md +24 -59
- package/skills/angular/SKILL.md +12 -25
- package/skills/api-connector-builder/SKILL.md +10 -27
- package/skills/api-design/SKILL.md +7 -14
- package/skills/article-writing/SKILL.md +1 -18
- package/skills/astro/SKILL.md +36 -54
- package/skills/author-skill/SKILL.md +41 -74
- package/skills/author-skill/evals/README.md +5 -5
- package/skills/author-skill/evals/cases.yaml +8 -8
- package/skills/author-skill/references/description-recipe.md +25 -26
- package/skills/author-skill/references/eval-authoring.md +1 -1
- package/skills/author-skill/references/rsc-conventions.md +1 -1
- package/skills/automation-flows/SKILL.md +6 -16
- package/skills/automation-strategy/SKILL.md +1 -9
- package/skills/aws-essentials/SKILL.md +6 -23
- package/skills/backups/SKILL.md +1 -7
- package/skills/bash-scripting/SKILL.md +5 -9
- package/skills/bookkeeping/SKILL.md +2 -10
- package/skills/brand-identity/SKILL.md +18 -44
- package/skills/brand-voice/SKILL.md +4 -31
- package/skills/building-agents/SKILL.md +20 -103
- package/skills/business-intelligence/SKILL.md +9 -23
- package/skills/calendar-scheduling/SKILL.md +11 -27
- package/skills/case-studies/SKILL.md +3 -8
- package/skills/chatbot/SKILL.md +6 -23
- package/skills/chrome-extension/SKILL.md +2 -2
- package/skills/clarify/SKILL.md +31 -72
- package/skills/clickhouse-analytics/SKILL.md +2 -8
- package/skills/client-onboarding/SKILL.md +17 -19
- package/skills/cloudflare/SKILL.md +3 -8
- package/skills/code-review/SKILL.md +10 -23
- package/skills/codebase-onboarding/SKILL.md +2 -7
- package/skills/cold-outreach/SKILL.md +9 -30
- package/skills/community/SKILL.md +4 -31
- package/skills/competitor-watch/SKILL.md +20 -35
- package/skills/compliance/SKILL.md +10 -37
- package/skills/compose-multiplatform/SKILL.md +1 -1
- package/skills/constitution/SKILL.md +8 -35
- package/skills/content-engine/SKILL.md +4 -16
- package/skills/context-budget/SKILL.md +3 -21
- package/skills/continuous-learning/SKILL.md +10 -40
- package/skills/contracts/SKILL.md +6 -17
- package/skills/coolify/SKILL.md +8 -14
- package/skills/cost-tracking/SKILL.md +3 -11
- package/skills/course-builder/SKILL.md +17 -45
- package/skills/course-storytelling/SKILL.md +26 -94
- package/skills/cpp/SKILL.md +26 -71
- package/skills/csharp-dotnet/SKILL.md +19 -38
- package/skills/customer-support/SKILL.md +14 -37
- package/skills/dashboard/SKILL.md +6 -26
- package/skills/data-cleaning/SKILL.md +37 -63
- package/skills/data-policy/SKILL.md +8 -21
- package/skills/data-scraper/SKILL.md +1 -7
- package/skills/debug/SKILL.md +10 -49
- package/skills/deployment/SKILL.md +38 -101
- package/skills/design/SKILL.md +34 -116
- package/skills/fable-operator/SKILL.md +1 -4
- package/skills/fastapi/SKILL.md +50 -82
- package/skills/flutter/SKILL.md +41 -89
- package/skills/go/SKILL.md +57 -105
- package/skills/harness/SKILL.md +52 -68
- package/skills/implement/SKILL.md +1 -1
- package/skills/init/SKILL.md +152 -168
- package/skills/marketing/SKILL.md +30 -80
- package/skills/nextjs/SKILL.md +42 -116
- package/skills/orient/SKILL.md +25 -20
- package/skills/parallel/SKILL.md +9 -75
- package/skills/plan/SKILL.md +92 -165
- package/skills/postgresdb/SKILL.md +52 -72
- package/skills/presentations/SKILL.md +49 -87
- package/skills/python/SKILL.md +23 -72
- package/skills/react/SKILL.md +19 -67
- package/skills/review/SKILL.md +22 -52
- package/skills/rust/SKILL.md +40 -115
- package/skills/sdd-init/SKILL.md +9 -14
- package/skills/secure-coding/SKILL.md +80 -109
- package/skills/ship/SKILL.md +25 -55
- package/skills/tasks/SKILL.md +37 -61
- package/skills/typescript/SKILL.md +22 -55
- package/skills/verify/SKILL.md +8 -32
- package/skills/viral-score/SKILL.md +122 -0
- package/skills/viral-score/evals/README.md +16 -0
- package/skills/viral-score/evals/cases.yaml +50 -0
- package/skills/vue-nuxt/SKILL.md +45 -106
- package/skills/worktrees/SKILL.md +24 -69
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: code-review
|
|
3
|
-
description: "Use
|
|
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
|
|
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;
|
|
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
|
|
123
|
+
## Anti-patterns
|
|
124
124
|
|
|
125
|
-
|
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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
|
|
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
|
|
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
|
|
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 —
|
|
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
|
-
|
|
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.
|
|
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,
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
65
|
-
|
|
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.
|
|
195
|
-
|
|
196
|
-
`materiality`
|
|
197
|
-
|
|
198
|
-
slower-than-daily
|
|
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
|
|
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
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
101
|
+
## Anti-patterns
|
|
120
102
|
|
|
121
|
-
|
|
|
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
|
|
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`.
|