Atie Daghlawi

Profile

Repository Guidelines

Repository Guidelines

Project Structure & Module Organization

This repository is a Jekyll site published through GitHub Pages. The dated post index at index.html and the About page at about.md define the main routes. Reusable templates live in _layouts/ and _includes/; dated posts and reports both belong in _posts/. The former /blog/ route is generated as a compatibility redirect from index.html, while adhoc/index.html is the compatibility route for the former report index. Keep styles in assets/, generated report data in _data/research_snapshot.json, and validation or capture utilities in scripts/. Historical material under rafts/ is limited to the legacy feed retained for compatibility; avoid extending it. Treat _site/ as generated output, not source.

Build, Test, and Development Commands

  • bundle install installs the Ruby dependencies pinned in Gemfile.lock.
  • bundle exec jekyll serve runs a local preview; restart it after changing _config.yml.
  • bundle exec jekyll build generates _site/ using the GitHub Pages-compatible dependency set.
  • python3 scripts/test_public_role_contract.py runs the Python unittest contract suite.
  • ruby scripts/validate_research_snapshot.rb validates the checked-in public data.
  • ruby scripts/check_built_site.rb _site checks routes, links, landmarks, and report invariants after a build.

Run the contract tests, snapshot validator, build, and built-site check before proposing a change.

Coding Style & Naming Conventions

Follow existing formatting: two-space indentation and frozen-string comments in Ruby; four-space indentation, type hints, snake_case, and unittest conventions in Python. Use two-space indentation in HTML, YAML, and CSS. Prefer semantic HTML, accessible landmarks, and existing CSS component patterns such as .site-header__inner. Name new report files with lowercase kebab-case slugs, for example adhoc/example-analysis.html. No repository-wide formatter is configured, so keep changes focused and match neighboring code.

Testing Guidelines

Add Python tests to scripts/test_*.py with methods named test_*. Extend the Ruby validators when changing routes, rendered structure, snapshot fields, or publication rules. There is no numeric coverage target; every changed contract should have a specific regression assertion.

Commit & Pull Request Guidelines

This is a single-maintainer repository. Work directly on master; do not create or switch to a feature branch unless the user explicitly requests one. Recent commits use short, imperative subjects, often Conventional Commit prefixes such as feat:. Keep each commit scoped to one coherent change. Pull requests should explain the user-visible result, list commands run, link relevant issues, and include screenshots for layout or styling changes. Call out redirects or public-data changes explicitly.

Security & Public Data

Never commit credentials, connection details, private records, or row-level source data. Publish only validated, allowlisted aggregates and do not hand-transcribe values from private systems.