A Governed Contribution Model for DevSpark Prompts

Documentation falls out of date the moment it's published because maintaining it is a chore with no immediate feedback. Prompts are different. If a DevSpark prompt is wrong — if it generates code that misuses a framework feature, applies a deprecated pattern, or hallucinates a convention that doesn't exist — the failure is immediate and visible. The developer sees bad output. The prompt needs to change.

That creates an unusual incentive structure: developers are highly motivated to fix prompts that affect their work, because the prompts are active parts of their development process rather than passive reference material. The contribution model I've built for DevSpark tries to harness that motivation without letting individual fixes accidentally break everyone else.

The Three-Tier Ownership Model

The same tiered architecture that governs prompt resolution — described in the tiered prompt model article — also governs where improvements belong:

User-scoped tier (.documentation/{username}/commands/): Improvements that reflect personal workflow preferences. If I want /devspark.specify to lead with failure modes before user stories because that's how my brain works, that's a user-scoped change. I make it myself, it takes effect immediately, and it affects nobody else. No review process, no approval needed.

Project tier (.documentation/commands/): Improvements that reflect this codebase's specific conventions. If a prompt generates authentication code that doesn't match this project's established AuthService pattern, the fix belongs in the project override. It's a PR against the project repository, reviewed by whoever maintains the project's constitution. Changes here affect everyone working on this codebase.

Framework tier (.devspark/templates/): Improvements that should propagate to everyone who uses DevSpark. If I find that the /devspark.critic prompt consistently misclassifies a particular category of risk — flagging it as showstopper when it's genuinely medium severity — that's a framework-level fix. It goes through the DevSpark repository's PR process, gets reviewed by the framework maintainers, and ships in the next release.

The routing question — which tier does this improvement belong in? — is the first decision point after discovering a prompt failure. The suggest-improvement workflow helps answer it: it analyzes which tier owns the failing prompt and scaffolds the improvement proposal for that tier.

The PR-Based Flow

For framework-tier improvements, the contribution path follows the same discipline I apply to code:

1. Fork or branch from the DevSpark repository
2. Identify the failing prompt in .devspark/templates/commands/ or .devspark/templates/prompts/
3. Make the targeted change — usually a few lines, rarely more than a section
4. Run the test suite (pytest tests/ in the DevSpark repository) — there's a growing collection of contract tests that validate prompt structure, frontmatter schemas, and command output format
5. Open a PR with the specific failure case described: which command, which context, what the agent produced, what it should have produced

The quality bar for framework prompt changes is high because the blast radius is large. A change that improves output for one project type might regress output for another. The PR description needs to explain not just what changed but why the change improves the general case, not just the specific case that triggered the discovery.

For project-tier improvements, the process is lighter. A PR against the project repository, reviewed by whoever owns the project's DevSpark configuration. The bar is: does this change improve output for this codebase without introducing new problems?

Prompts as Active Standards

The insight that has shaped this contribution model most is that prompts are active standards, not passive documentation. When a prompt changes, every subsequent invocation uses the new version. There's no lag between the standard changing and the behavior changing — it's immediate.

That immediacy cuts both ways. A good prompt change takes effect the next time anyone runs the command. A bad prompt change does too. The review process for framework-tier changes isn't bureaucracy — it's the mechanism that prevents well-intentioned fixes from silently breaking workflows for projects that weren't part of the testing.

I've been on the receiving end of upstream changes that broke local behavior, and I've shipped upstream changes that probably broke something I wasn't aware of. The lesson from both experiences is the same: the contribution model needs to make it easy to improve things and hard to break things. Git-based PRs with a clear test suite and a required description of the specific failure case being fixed is the best balance I've found.

When to Contribute Upstream

The honest filter I use: if I've hit a prompt failure more than once, in more than one project, the fix probably belongs upstream. If it's specific to one codebase's unusual conventions, it belongs in the project override. If it's purely about my personal thinking style, it's a user-scoped change.

The suggest-improvement workflow makes this decision visible by showing me which tier owns the failing prompt before I start writing the fix. That context matters — I've saved time by realizing mid-investigation that the "framework bug" I was about to file was actually a project-specific pattern that my project override should handle.

If you encounter a DevSpark prompt that consistently fails in a reproducible way — a specific command, a specific context, a specific wrong output — the DevSpark issue tracker is the right place to start. Including the command name, the project context, and the specific failure case makes the report actionable rather than vague. The framework improves through exactly these specific, reproducible cases — not through general complaints that the AI got it wrong.