Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (76 loc) · 4.32 KB

CONTRIBUTING.md

File metadata and controls

105 lines (76 loc) · 4.32 KB
Raw

Contributing to Subliminal Audio Protocol Generator

Thanks for your interest. This project sits at the intersection of open-source tooling and evidence-based psychology, so contributions need to meet a slightly higher bar than typical software projects.

Types of Contribution

🟢 Welcome

  • Bug fixes — especially in the affirmation generator, compatibility checker, or export functions
  • New export formats — e.g. iCal export, Obsidian template, HTML dashboard
  • New conflict-pair patterns — if you can cite a source for why two goal types create identity tension
  • Documentation improvements — clearer examples, better onboarding, translations
  • Accessibility — making the protocol output more usable for people with visual/hearing impairments
  • Test coverage — unit tests for the builder functions
  • Pandoc templates — custom LaTeX templates for nicer PDFs

🟡 Needs Justification

  • New affirmation variant transforms — only if grounded in research (cite the paper)
  • Changes to the session structure — the phase order and durations are evidence-backed; any change needs a citation
  • New entrainment frequencies — must be supported by peer-reviewed studies (432 Hz won't pass)

🔴 Not Acceptable

  • Unverified claims in the research intelligence file — everything tagged [H] must trace to a peer-reviewed or declassified source. No blog posts, no YouTube videos, no "ancient wisdom."
  • Trauma-processing features — this tool explicitly avoids trauma work for safety reasons. Do not add affirmations that instruct users to revisit traumatic memories.
  • Memory-erasure framing — affirmations must use "build new pathways alongside" language, never "erase" or "delete" old beliefs.
  • Strobe/flash elements — epilepsy risk. Not negotiable.
  • Copyrighted content — don't paste affirmations, scripts, or audio from commercial subliminal products.

Process

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Make your changes
  4. Test — at minimum, run the generator against research-intelligence.md and verify the output: 
    python3 scripts/build_protocol.py \
  -i research-intelligence.md \
  -o /tmp/test-output.md \
  --goal "Test goal" \
  --identity-shift "Old -> New" \
  --behaviors "Test behavior" \
  --values "TestValue" \
  --affirmation-variants 2 \
  --voice-script --calendar --checkin --export-json
  5. If adding research findings to research-intelligence.md, tag each with [H], [M], or [L] and include the full citation
  6. Commit with a clear message
  7. Open a pull request

Adding Research Findings

The research-intelligence.md file is the backbone of the protocol. Findings must follow this format:

## Domain Name

- [H] Finding description (Author et al. Year, Journal)
- [M] Finding description (Author et al. Year, Journal)
- [L] Finding description (Author et al. Year, Journal)

Confidence levels:

  • [H] = High: peer-reviewed, replicated, or meta-analytic
  • [M] = Moderate: single study, mixed evidence, or promising but not yet replicated
  • [L] = Low: preliminary, theoretical, or anecdotal — used for context but never included in protocol output

Only [H]-tagged findings are parsed into the protocol. If you add an [M] finding that you believe should be promoted to [H], include a brief justification in your PR.

Code Style

  • Python 3.10+ (use X | Y union syntax, not Union[X, Y])
  • Functions are pure where possible — build_protocol() takes data, returns a string
  • No external dependencies in build_protocol.py (stdlib only). Pandoc is optional.
  • Keep the CLI interface flat — flags, not subcommands
  • Type hints on all function signatures

Safety Checklist for PRs

Before merging, verify:

  • No trauma-reactivation instructions added
  • No memory-erasure framing in generated output
  • No session duration escalation beyond 25 min
  • No unverified claims promoted to [H] confidence
  • Medical disclaimer remains as first section in generated protocol
  • Exclusion criteria are intact
  • No new external dependencies introduced without justification

Questions?

Open an issue. Be specific about what you're trying to achieve and what's blocking you.