CONTRIBUTING.md

# Contributing to STEM BIO-AI

Thank you for your interest in improving STEM BIO-AI. This document explains how to contribute effectively.

## Types of Contributions

### 1. Discrimination Examples (Most Common)

When you run a live audit and encounter a boundary case that existing examples do not cover, add it to the appropriate file in `discrimination/`.

**Format:**
```
TRIGGERS (deduct -N):
  "[exact quoted text from README]"
    -- [why this triggers the item]

DOES NOT TRIGGER:
  "[exact quoted text]"
    -- [why this does not trigger]
```

**Submit via:** Pull request to `discrimination/` files only. No spec changes needed.

### 2. Clinical Adjacency Triggers

If you encounter a clinical tool, library, or keyword not in the current 60+ trigger list, add it to `references/clinical_adjacent_triggers.md`.

**Requirements:**
- Tool must be used in actual clinical or patient-adjacent contexts
- Include the CA severity tier (DIRECT / INDIRECT / PLANNED)
- Provide a real-world usage example

### 3. Template Improvements

Templates in `templates/` can be improved for clarity, completeness, or institutional compatibility. Changes must not alter the scoring logic or public output contract described in `docs/SCORING_RATIONALE.md`, `docs/API_CONTRACT.md`, and the active CLI/report surfaces.

### 4. Script Improvements

Scripts in `scripts/` can be improved for portability, accuracy, or coverage. All scripts must:
- Run on bash (Linux/macOS) without external dependencies
- Include `set -euo pipefail` error handling
- Document their purpose in header comments
- Not modify any files outside the audit output directory

### 5. Rubric and Scoring Modifications (Requires Discussion)

The public contribution path for rubric changes is the active documentation surface, not `spec/`.

`spec/` is retained as local-only private material and is ignored by Git. Do not target `spec/` in public pull requests.

Score-affecting rubric or policy changes still follow strict rules:

**VARIABLE items** (LLM discretion, evidence narration, output language):
- Can be discussed and proposed via PR with rationale in active docs

**IMMUTABLE items** (score formula, tier boundaries, weights, hard floors):
- Require a new version number (e.g., 1.1.1 -> 1.2.0)
- Must be discussed in a GitHub Issue first
- Must include impact analysis on existing audit results
- Must be approved by a maintainer

Target files for public discussion/proposals:

- `docs/SCORING_RATIONALE.md`
- `docs/API_CONTRACT.md`
- `docs/CALIBRATION_PROFILE_DESIGN.md`
- `CHANGELOG.md`

### 6. Calibration Profile Proposals

Calibration contributions are welcome, but they follow a stricter path than normal docs or discrimination-example edits.

Allowed contribution shapes:

- propose new `derive` / `simulate` posture examples
- propose bounded `preview_only` deltas
- propose an `experimental` named profile with documented diffs
- provide benchmark or repository-side comparison evidence for profile promotion

Not allowed as direct contribution outcomes:

- silently changing the authoritative default scoring policy
- introducing ad hoc CLI numeric tuning knobs
- promoting score-affecting detector logic without documented policy/rationale review

If you want to change calibration behavior:

1. describe the domain posture you want
2. show the `default` vs preview/profile comparison on a real repository
3. document the proposed policy diff
4. explain whether the change should stay `preview_only`, become `experimental`, or be considered for future authoritative promotion

Authoritative score policy changes still require governed profile promotion, rationale updates, and maintainer review. See [`docs/CALIBRATION_PROFILE_DESIGN.md`](docs/CALIBRATION_PROFILE_DESIGN.md).

## Pull Request Process

1. Fork the repository
2. Create a feature branch (`git checkout -b add-h2-example`)
3. Make changes
4. Run validation (`bash scripts/validate_skill_structure.sh`)
5. Submit PR with description of:
   - What changed
   - Why (link to live audit finding if applicable)
   - Impact on existing scores (if any)

## Code of Conduct

- STEM BIO-AI evaluates repository artifacts, not people
- Contributions must not introduce personal attacks or bias
- Clinical safety is the priority; marketing is not
- Evidence-based claims only; speculation is not acceptable

## Questions?

Open a GitHub Issue with the `question` label.