Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
52 lines (34 loc) · 2.57 KB

CONTRIBUTING.md

File metadata and controls

52 lines (34 loc) · 2.57 KB
Raw

Contributing

Dev Guardrails is built from real failure patterns observed in production AI-assisted development. Contributions that document new patterns, improve existing guardrails, or add stack-specific checklists are welcome.

How to Contribute

Reporting a New Anti-Pattern

If you've observed a recurring AI failure that isn't covered by the existing anti-patterns, open an issue with:

  1. What happens — Describe the failure behavior concretely
  2. Why it happens — Your understanding of why the AI makes this mistake
  3. Corrective behavior — What the AI should do instead
  4. Evidence — Examples from real projects (anonymized) where this pattern occurred

Adding a Stack-Specific Checklist

If you work with a stack that isn't covered (e.g., Django, Flutter, Terraform), you can add a checklist to references/checklists.md. Follow the existing format:

## [Stack Name] Checklist

Specific to [stack] development:

- [ ] Item that addresses a real, recurring failure
- [ ] Another item

Each item should address a specific failure mode, not a general best practice. "Write clean code" is not a checklist item. "Verify RLS policies exist for new tables" is.

Improving Existing Content

If you find a guardrail that's too vague, an anti-pattern that's missing a corrective behavior, or a checklist that's incomplete, submit a PR with the improvement. Include a brief explanation of what failure the change prevents.

Guidelines

  • Be specific. Every rule, anti-pattern, and checklist item should address a concrete, observable failure. Avoid generic advice.
  • Include the "why." Understanding why a failure happens is more effective than memorizing a rule.
  • Keep it framework-agnostic in the core files. Stack-specific content goes in dedicated checklist sections.
  • Test with real AI sessions. Before proposing a new guardrail, verify that it actually changes the AI's behavior when included in the skill.

Structure

SKILL.md                        → Main process (phases, protocols, decision guide)
references/anti-patterns.md     → Failure catalog (what goes wrong and why)
references/checklists.md        → Verification lists (concrete items to check)
references/product-thinking.md  → Product/UX framework (think like a product owner)
references/testing-strategy.md  → Testing hierarchy (verify it works, not just compiles)

When adding content, put it in the right file. New failure patterns go in anti-patterns.md. New verification items go in checklists.md. New conceptual frameworks go in their own reference file.