chore: add issue templates, PR template and contributing guide

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug Report
+about: Report reproducible errors, unexpected exceptions, or incorrect simulation outputs
+title: "[BUG] "
+labels: bug
+assignees: ""
+---
+
+### Problem Description
+<!-- Clear and concise explanation of what the bug is. -->
+
+### Steps to Reproduce
+1. Import or load data: `...`
+2. Call function with parameters: `...`
+3. Run command: `...`
+
+### Expected Behavior
+<!-- What you expected to happen. -->
+
+### Actual Behavior / Error Traceback
+```python
+# Paste full error traceback here

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,21 @@
+---
+name: Documentation Task / Improvement
+about: Propose new documentation, tutorials, docstring improvements, or corrections
+title: "[DOCS] "
+labels: documentation
+assignees: ""
+---
+
+### Documentation Target
+<!-- What needs to be documented, improved, or corrected? (e.g., API docstring, tutorial notebook, MkDocs guide, README) -->
+
+### Motivation / Problem
+<!-- Why is this documentation needed? Is the current explanation outdated, missing, or unclear? -->
+
+### Proposed Changes
+- [ ] Add/update docstrings in `path/to/module.py`
+- [ ] Write or refine documentation page/tutorial in `docs/`
+- [ ] Update code examples to reflect current API behavior
+
+### References & Context
+<!-- Link to relevant code, papers, or related issues, if applicable. -->

.github/ISSUE_TEMPLATE/feature_task.md

@@ -0,0 +1,19 @@
+---
+name: Feature / Task Request
+about: Propose a new feature, enhancement, or research task
+title: "[FEAT] "
+labels: enhancement
+assignees: ""
+---
+
+### Objective
+<!-- What problem does this solve, or what new capability does it introduce? -->
+
+### Technical Specifications & Context
+<!-- Provide implementation details: affected modules, mathematical formulas, expected inputs/outputs, or references. -->
+
+### Acceptance Criteria (Definition of Done)
+- [ ] Implementation completed in the target module
+- [ ] Unit test(s) covering standard and edge cases added to `tests/`
+- [ ] Documentation or usage example provided (if public API changed)
+- [ ] Pull request passes CI checks and is reviewed

.github/ISSUE_TEMPLATE/onboarding_task.md

@@ -0,0 +1,23 @@
+---
+name: Onboarding / Good First Issue
+about: Well-scoped task suitable for new students joining the team
+title: "[ONBOARDING] "
+labels: good first issue, documentation
+assignees: ""
+---
+
+### Task Description
+<!-- Describe the specific, small-scope task to be completed. -->
+
+### Relevant Files
+- `path/to/file`
+- `tests/`
+
+### Step-by-Step Guidance
+1. Checkout the branch from latest `main`.
+2. Follow the setup in `README.md` and activate the virtual environment.
+3. Make the specified adjustments.
+4. Run tests and linter to verify.
+
+### Expected Deliverable
+- A pull request with clean commits following the repository conventions.

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+### Description
+<!-- Provide a concise summary of the changes made and the motivation behind them. -->
+
+### Related Issue
+<!-- Link the related issue to close it automatically upon merge, e.g., Closes #12 -->
+Closes #
+
+### Changes Made
+- [ ] Core implementation / algorithmic changes
+- [ ] Added or updated unit tests
+- [ ] Updated documentation / docstrings / examples
+
+### Contributor Checklist
+- [ ] The code runs locally without errors
+- [ ] All unit tests pass locally (`pytest`)
+- [ ] Static analysis and formatting pass (`ruff check .`)
+- [ ] Docstrings follow the project standard (inputs, outputs, exceptions)