contribute-finding

name

contribute-finding

description

For Claude sessions running in a consumer project (any project where ravenclaude-core is installed). Triggered when you discover a cross-domain finding worth contributing back to the RavenClaude marketplace — either spontaneously, or when the user says "contribute this," "save to RavenClaude," "this is worth keeping," or similar. Walks through the qualifying check, picks the right shape (lesson, best-practice, or both), and formats a copyable staging submission the user can drop into RavenClaude/docs/staging/incoming/.

Skill: contribute-finding

You're working in a consumer project that has ravenclaude-core installed. Something you just learned or codified is worth sending back to the marketplace so future consumers benefit. This skill is the formatting playbook so the maintainer can review and promote your submission with zero rewriting.

The marketplace maintainer (typically Matt) reviews staged submissions with the review-staged-contributions skill. Your job is to give them a clean artifact to review.

---

Step 1 — Does the finding qualify?

The marketplace's cross-domain docs/ directory is for findings that apply to any Claude work, any plugin, any project. Run all three checks:

• ✅ Cross-domain. Power Platform-specific, finance-specific, EdTech-specific findings do NOT go here — they belong inside the relevant plugin's skills/<skill>/resources/ folder. Cross-domain means: a different consumer working in a different stack would still benefit.
• ✅ Generalizes. A rule or a story another collaborator (or future-you in a different project) would benefit from — not a one-off preference and not a war story about a single client.
• ✅ Still useful in a year. If the finding is a hot take on a beta feature or a quirk of one tool's current version, it's probably not load-bearing enough to codify.

If any one of those is no, do not submit. Tell the user you considered contributing but the finding didn't qualify, and explain which check it failed. Save it to project-local memory instead.

---

Step 2 — Pick the shape

Use the rule from lessons-vs-best-practices:

Finding shape	Submission type	Why
We tried X, it failed because Y, so we now do Z (story)	Lesson	Goes into docs/memory-bank/lessons-learned.md as a dated entry
Timeless rule with no failure story behind it	Best-practice	Goes into docs/best-practices/<slug>.md as its own file
Both a story AND a generalizable rule	Both — submit two separate files	Each promotes independently and they cross-link on the maintainer side

One staging file = one canonical doc on promotion. Do not combine a lesson and a best-practice in one file.

---

Step 2.5 — Tag the topic

Pick the topic: value that best describes the expertise the finding draws on. On the maintainer side, the review skill spawns the matching specialist agent to analyze whether the finding generalizes or is one-off — so getting the topic right routes the submission to the right reviewer.

topic:	Expert who'll review on the maintainer side	Use when the finding is about…
architecture	ravenclaude-core / architect	system design, trade-offs, structural choices
backend	ravenclaude-core / backend-coder	server, API, DB, jobs, integrations
frontend	ravenclaude-core / frontend-coder	UI, components, client state, styling
fullstack	ravenclaude-core / fullstack-coder	client/server crossings as one unit
testing	ravenclaude-core / tester-qa	test design, flake hunting, coverage
code-review	ravenclaude-core / code-reviewer	review patterns, diff hygiene
security	ravenclaude-core / security-reviewer	auth, crypto, secrets, untrusted input
research	ravenclaude-core / deep-researcher	sourcing, verification, comparison
documentation	ravenclaude-core / documentarian	stakeholder prose, runbooks, READMEs
design	ravenclaude-core / designer	UX, wireframes, visual hierarchy
prompt-engineering	ravenclaude-core / prompt-engineer	agent/skill prompts, prompt patterns
project-management	ravenclaude-core / project-manager	RAID, status, cadence, stakeholders
partner-success	ravenclaude-core / partner-success-manager	QBR, success plans, health scoring
power-platform	best-fit power-platform agent (router picks by subtopic)	Power Platform stack specifics
other	architect (fallback)	cross-cutting findings that don't fit above

If the finding spans two topics (e.g., security + backend), pick the one the expert should weigh in on most heavily — usually the more specialized one. The maintainer can request a second-opinion route during review if needed.

---

Step 3 — Scrub for safety before drafting

Before you write a single word of submission:

• Remove client names, tenant IDs, real GUIDs, internal URLs, email addresses, account numbers.
• Replace specifics with placeholders: <CLIENT>, <TENANT_ID>, contoso.crm.dynamics.com, [e-mail].
• Read it as a stranger: would anyone trace this back to a real engagement? If yes, scrub harder.

This step is non-negotiable. The marketplace is private today but designed to remain shareable across projects, contractors, and (eventually) external collaborators.

---

Step 4 — Draft using the right template

Wrap the entire submission in one fenced code block labelled RAVENCLAUDE-STAGING-SUBMISSION. The user copies that block verbatim — no edits needed.

Lesson template

```markdown RAVENCLAUDE-STAGING-SUBMISSION
<!-- RAVENCLAUDE-STAGING-METADATA
type: lesson
topic: <one of: architecture | backend | frontend | fullstack | testing | code-review | security | research | documentation | design | prompt-engineering | project-management | partner-success | power-platform | other>
proposed-by: <short context — e.g. "consumer project building a Dataverse flow integration">
proposed-on: YYYY-MM-DD
target-file: docs/memory-bank/lessons-learned.md
status: pending
-->

## YYYY-MM-DD — Short title naming the rule or finding

**Context:** What we were trying to do. 1–2 sentences.

**What we tried first:** The path that failed. 1–2 sentences.

**Why it failed:** The actual reason, with technical detail. 2–4 sentences.

**What works:** The canonical solution. 2–4 sentences.

**How to apply:**
- When this rule fires, what to do. 1–2 bullets.

**Trace:** Origin context (this consumer project, generalized), pointers to any external authoritative source if relevant.
```

Best-practice template

```markdown RAVENCLAUDE-STAGING-SUBMISSION
<!-- RAVENCLAUDE-STAGING-METADATA
type: best-practice
topic: <one of: architecture | backend | frontend | fullstack | testing | code-review | security | research | documentation | design | prompt-engineering | project-management | partner-success | power-platform | other>
proposed-by: <short context>
proposed-on: YYYY-MM-DD
target-file: docs/best-practices/<descriptive-slug>.md
status: pending
-->

# <Short rule name — what this doc tells you to do or not do>

**Status:** _Pick one — delete the others._
- **Absolute rule** — never break this.
- **Primary diagnostic** — when symptom X appears, check this first.
- **Pattern** — strong default; deviate only with a written reason.

**Domain:** _e.g. ALM, Identity, Web API, Solution mechanics, Agent design, Cross-domain._

**Applies to:** _Which plugin(s), tool(s), or project type(s)._

---

## Why this exists

_2–5 sentences on the rationale. Why is this worth codifying?_

## How to apply

_Concrete, copy-paste-grade guidance._

**Do:**
- _…_

**Don't:**
- _…_

## Edge cases / when the rule does NOT apply

_Known exceptions._

## See also

_Repo-relative cross-references._

## Provenance

_Where this rule came from. Be specific._

---

_Last reviewed: YYYY-MM-DD by `<short context or github handle>`_
```

---

Step 5 — Hand off to the user

After you print the staging block, tell the user — concisely — what to do with it. Phrase it like:

I've drafted a RAVENCLAUDE-STAGING-SUBMISSION above. To submit it:

1. Copy the entire fenced block (including the <!-- RAVENCLAUDE-STAGING-METADATA --> comment).
2. In the RavenClaude repo, create the file docs/staging/incoming/YYYY-MM-DD-<slug>.md where the date and slug match the metadata.
3. In your RavenClaude Claude Code session, run /review-staged-contributions to walk it through the keep/update/deny review.

If the user has their RavenClaude session open already, you can stop there — they'll handle the rest. If not, mention it'll wait in docs/staging/incoming/ until they're ready.

What happens on the maintainer side (so you can set expectations): The review skill doesn't take your submission at face value. It runs two gates before the maintainer sees the keep/update/deny prompt:

1. Security sweep — automated pattern scan (looks for leaked credentials, real identifiers that weren't scrubbed, prompt-injection signals, dangerous code examples, non-canonical external URLs) plus a read by the security-reviewer agent. Submissions with leaked secrets, prompt-injection content, or dangerous unscoped code get BLOCKED and are denied or routed back for scrubbing.
2. Expert analysis — the agent matching the topic: you tagged analyzes whether the finding generalizes (applies to anyone working in that topic) or is one-off (specific to your situation). The expert verdict appears alongside your submission in the maintainer's prompt.

This is why Step 3 (scrub for safety) is non-negotiable: a well-scrubbed submission with the right topic tag flies through both gates. An unscrubbed one — even if the finding itself is brilliant — gets blocked or routed for revision before promotion.

---

Anti-patterns

• Do not open a PR directly to RavenClaude from a consumer project. The staging path is lighter, routes through the same review, and doesn't require the consumer to have push permissions on the marketplace.
• Do not submit content you haven't scrubbed for client identifiers. The maintainer's review is for quality and fit, not for redacting secrets.
• Do not combine multiple findings in one staging file. Each file becomes one canonical doc on promotion.
• Do not invent content for sections you can't actually fill. If the lesson template's "What we tried first" / "Why it failed" sections feel empty, the finding is probably a best-practice (no failure story behind it), not a lesson.
• Do not submit personal preferences (your editor config, your working-style quirks). Those belong in project-local memory at ~/.claude/projects/.../memory/, not in the cross-domain marketplace.