Copilot instructions (swot)

Big picture

This is a local-first Streamlit app with a single entrypoint: app.py.
UX is intentionally constrained to exactly three views (no extra pages):
```
Areas
```
,
```
SWOT
```
,
```
Actions
```
.
- Navigation labels are centralized in swot_app/ui.py (
```
NAV_OPTIONS
```
  ) and are unit-tested.

Architecture & data flow

UI/state lives in Streamlit

st.session_state

areas

list[AreaNode]

actions

list[ActionItem]

Domain model is simple immutable dataclasses in swot_app/models.py.
Core domain logic is kept pure and testable under
```
swot_app/
```
:
- Validation + scoring: swot_app/compute.py (
```
validate_areas
```
  ,
```
compute_scores
```
  ,
```
area_paths
```
  ).
- Treemap sizing/coloring: swot_app/treemap.py (sibling-normalized sizing; adds a synthetic
```
Overall
```
  root via
```
with_overall_root()
```
  for rendering only).
- Exports: swot_app/exporters.py (functions return
```
bytes
```
  /
```
str
```
  for Streamlit download buttons).
- Project Save/Import ALL: swot_app/project_io.py (
```
SCHEMA_VERSION = "1"
```
  ).

Project-specific rules (important)

Weights are sibling-relative only (treemap sizing): a node’s
```
weight
```
is only compared to its siblings; a parent’s
```
weight
```
scales its whole subtree vs other parents.
Score precedence:
```
score_override
```
wins; otherwise leaf uses
```
score
```
; parent uses weighted average of children.
- If any child effective score is missing, the parent effective score becomes
```
None
```
  (not an error).
- A division-by-zero error happens only when all child weights sum to
```
0
```
  .
Treemap synthetic root is not persisted; persistence/export uses the user’s real area list.

Import/export conventions

Area IDs default to
```
a-xxxxxxxx
```
(see
```
_default_id()
```
in swot_app/importers.py); keep IDs stable in exports.
Save/Export ALL writes timestamped JSON files:
```
prefix_YYYYMMDD_HHMMSS.json
```
into the configured export folder.
- The default folder is
```
exports/
```
  and it is gitignored; do not commit generated exports.
Actions importers require
```
title
```
+
```
linked_area_id
```
(see swot_app/actions_importers.py).

Developer workflows (Windows/conda)

Run app:

conda run -n swot streamlit run app.py --server.port 8501

Run tests (preferred):
```
conda run -n swot python -m pytest -q
```
- Note:
```
pytest -q
```
  is supported via conftest.py adding the repo root to
```
sys.path
```
  .

Traceability:

conda run -n swot python scripts/check_traceability.py

(add

--strict-testcases

to make test-case coverage blocking).

When changing behavior

Update the PRD/HLD/plan/test-cases docs as needed and keep traceability green:
- docs/PRD.md, docs/HLD.md, docs/IMPLEMENTATION_PLAN.md, docs/test_cases.md.
Prefer adding/adjusting unit tests under
```
tests/
```
for pure-function changes (compute/import/export/IO).

Architecture & data flow

UI/state lives in Streamlit

st.session_state

areas

list[AreaNode]

actions

list[ActionItem]

Domain model is simple immutable dataclasses in swot_app/models.py.

Core domain logic is kept pure and testable under

swot_app/

Validation + scoring: swot_app/compute.py (
```
validate_areas
```
,
```
compute_scores
```
,
```
area_paths
```
).
Treemap sizing/coloring: swot_app/treemap.py (sibling-normalized sizing; adds a synthetic
```
Overall
```
root via
```
with_overall_root()
```
for rendering only).
Exports: swot_app/exporters.py (functions return
```
bytes
```
/
```
str
```
for Streamlit download buttons).
Project Save/Import ALL: swot_app/project_io.py (
```
SCHEMA_VERSION = "1"
```
).

Project-specific rules (important)

Weights are sibling-relative only (treemap sizing): a node’s

weight

is only compared to its siblings; a parent’s

weight

scales its whole subtree vs other parents.

Score precedence:

score_override

wins; otherwise leaf uses

score

; parent uses weighted average of children.

If any child effective score is missing, the parent effective score becomes
```
None
```
(not an error).
A division-by-zero error happens only when all child weights sum to
```
0
```
.

Treemap synthetic root is not persisted; persistence/export uses the user’s real area list.

Import/export conventions

Area IDs default to

a-xxxxxxxx

(see

_default_id()

in swot_app/importers.py); keep IDs stable in exports.

Save/Export ALL writes timestamped JSON files:

prefix_YYYYMMDD_HHMMSS.json

into the configured export folder.

The default folder is
```
exports/
```
and it is gitignored; do not commit generated exports.

Actions importers require

title

linked_area_id

(see swot_app/actions_importers.py).

Developer workflows (Windows/conda)

Run app:

conda run -n swot streamlit run app.py --server.port 8501

Run tests (preferred):

conda run -n swot python -m pytest -q

Note:
```
pytest -q
```
is supported via conftest.py adding the repo root to
```
sys.path
```
.

Traceability:

conda run -n swot python scripts/check_traceability.py

(add

--strict-testcases

to make test-case coverage blocking).

Copilot instructions (swot)

Copilot instructions (swot)

Big picture

Architecture & data flow

Project-specific rules (important)

Import/export conventions

Developer workflows (Windows/conda)

When changing behavior

Related Skills

Markdown Converter

Nano Banana Pro

1password

Copilot instructions (swot)

Big picture

Architecture & data flow

Project-specific rules (important)

Import/export conventions

Developer workflows (Windows/conda)

When changing behavior