# Step 1: research-evidence

## Read These Files First

Read the following files before editing:

- `/AGENTS.md`
- `/docs/PRD.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- `/docs/requirements/euler-beam-3d.md`
- `/docs/research/README.md`

## Task

Create `/docs/research/euler-beam-3d-research.md`.

Summarize the evidence needed to implement the approved kernel-first 3D Euler-Bernoulli beam increment. The document must be implementation-oriented and must include:

- supported theory: straight prismatic Euler-Bernoulli beam, axial, torsion, and two uncoupled bending planes
- assumptions and applicability limits
- local DOF ordering and sign convention used by the planned matrix
- source reliability classification
- benchmark-style checks that do not require external reference solver execution:
  - local stiffness symmetry
  - axial-only response
  - torsion-only response
  - bending about local `y`
  - bending about local `z`
  - rigid body translation/rotation zero internal forces in local coordinates
  - global transform identity for an axis-aligned beam
- risks: orientation vector parallel to element axis, near-zero length, nonpositive section constants, ill-conditioning for very slender elements

If internet access or a FEM wiki is used, cite sources briefly. Do not include long copyrighted excerpts.

Do not create C++ files in this step.

## Tests To Write First

- No C++ test is required in this documentation-only step.

## Acceptance Criteria

```powershell
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_workspace.py
```

## Verification Notes

1. Confirm the research document ties each source or theory point to a planned implementation check.
2. Confirm unresolved items are listed as risks or open issues instead of silently assumed.
3. Update `phases/euler-beam-3d/index.json` step 1:
   - success: `"status": "completed"`, `"summary": "3D Euler beam research evidence added"`
   - failure after retries: `"status": "error"`, `"error_message": "<specific error>"`
   - blocked: `"status": "blocked"`, `"blocked_reason": "<specific reason>"`

## Forbidden

- Do not modify source, test, reference, or I/O contract files.