[limen GH-organvm-public-process-14] [STRANGER-TEST] Session 2: Technical Writer

.github/ISSUE_TEMPLATE/first_contribution.md

@@ -17,7 +17,7 @@ Where is the relevant code/content? Link files or sections.
 ## Definition of Done
 
 - [ ] Concrete acceptance criteria are listed
-- [ ] Required checks to run are listed (`validate.sh`, repo tests, etc.)
+- [ ] Required checks to run are listed (docs preview, Jekyll build, CI data-drift check, etc.)
 - [ ] Scope fits a first contribution (<1 day focused work)
 
 ## Constraints

.github/PULL_REQUEST_TEMPLATE.md

@@ -16,8 +16,9 @@
 
 <!-- How did you test these changes? -->
 
-- [ ] `../validate.sh` passes from workspace root
-- [ ] `bundle exec jekyll build --strict_front_matter --future` passes
+- [ ] Docs-only change previewed and self-reviewed
+- [ ] `bundle exec jekyll build --strict_front_matter --future` passes for content/layout/config changes
+- [ ] CI data-drift checks considered for `_posts/` or `_logs/` changes
 - [ ] New tests added (if applicable)
 - [ ] Manual testing performed
 

CONTRIBUTING.md

@@ -1,89 +1,118 @@
 # Contributing to public-process
 
-Thank you for your interest in contributing to this project.
+Thank you for helping improve `public-process`.
 
-## Overview
+This repository is the essay site for the organvm system. If you came here
+looking for essays, you are in the right place.
 
-Public Process is the essay publication platform for the organvm system. It is a Jekyll blog that hosts essays about building in public, creative systems, autonomous infrastructure, and the philosophy behind the eight-organ model. Essays are written in Markdown with YAML frontmatter.
+## Quick Orientation
 
-**Stack:** Jekyll blog, Ruby, Markdown essays
+- Complete dated essay corpus: `_posts/YYYY-MM-DD-slug.md`
+- Curated long-form essay collection: `essays/meta-system/` and
+  `essays/subsidiary/`
+- Site pages: `index.md`, `about.md`, `reading.md`, `dashboard.md`
+- Generated indexes and feeds: `data/`
+- Jekyll configuration: `_config.yml`, `_layouts/`, `_includes/`
 
-## Prerequisites
+For most writing and editing work, start in `_posts/` or `essays/`.
 
-- Git
-- Ruby 3.3.x (see `.ruby-version`)
-- Bundler 4.0.3 (see `Gemfile.lock`)
-- A GitHub account
+## Terms Used Here
 
-## Development Setup
+| Term | Plain meaning |
+|------|---------------|
+| `public-process` | This repository: the public essay and methodology site. |
+| Organ V / Logos | The part of organvm responsible for essays, public process, and explanation. |
+| organvm | The broader eight-organ project this site documents. |
+| Essay | A Markdown file with a short YAML metadata block at the top. |
+| Frontmatter | The YAML metadata block between `---` lines at the top of an essay. |
+| Stranger Test | A check that a first-time reader can understand the purpose, status, and next step without private context. |
+| PR | Pull request: the GitHub review request for your proposed change. |
+
+## Good First Contributions
+
+- Fix a typo, broken link, confusing sentence, or stale cross-reference.
+- Clarify an essay introduction or section heading.
+- Improve onboarding docs such as this file.
+- Add missing metadata only when the expected value is clear from nearby files.
+- Draft a new essay only when there is an issue or maintainer note defining the scope.
+
+Keep first changes small and easy to review. A useful one-paragraph correction is
+better than a broad rewrite that mixes many decisions.
+
+## Setup
+
+For docs-only edits, GitHub's web editor is enough. For local preview or changes
+to essays, layouts, includes, or configuration, use the Jekyll setup:
 
 ```bash
-# Clone your fork
 git clone https://github.com/YOUR_USERNAME/public-process.git
 cd public-process
-
-# Ensure Homebrew Ruby/Bundler are first on PATH (macOS/Homebrew)
-export PATH="/opt/homebrew/opt/ruby/bin:$PATH"
-
-# Install Ruby dependencies
-gem install bundler:4.0.3
 bundle install
-
-# Serve locally
 bundle exec jekyll serve
-
-# Site available at http://localhost:4000
 ```
 
-## How to Contribute
+The local site is available at `http://localhost:4000/public-process/`.
+
+This repo targets Ruby 3.3.x. If Bundler is missing, install the version from
+`Gemfile.lock`:
 
-### Reporting Issues
+```bash
+gem install bundler:4.0.3
+```
 
-- Use GitHub Issues for bug reports and feature requests
-- Use the provided issue templates when available
-- Include clear reproduction steps for bugs
-- For documentation issues, specify which file and section
+## Making a Change
 
-### Making Changes
+1. Fork the repository on GitHub.
+2. Create a branch for the change:
 
-1. **Fork** the repository on GitHub
-2. **Clone** your fork locally
-3. **Create a branch** for your change:
    ```bash
-   git checkout -b feat/your-feature-name
+   git checkout -b docs/clarify-contributor-guide
    ```
-4. **Make your changes** following the code style guidelines below
-5. **Test** your changes:
-   ```bash
-   bundle exec jekyll build --strict_front_matter
-   ```
-6. **Commit** with a clear, imperative-mood message:
+
+3. Make the smallest useful edit.
+4. Run the check that matches the change.
+5. Commit with a short, imperative message:
+
    ```bash
-   git commit -m "add validation for edge case in parser"
+   git commit -m "clarify contributor guide"
    ```
-7. **Push** your branch and open a Pull Request
 
-### Code Style
+6. Open a pull request and link the related issue when there is one.
+
+## Checks to Run
+
+Use the lowest check that actually covers your change:
+
+| Change type | Local check |
+|-------------|-------------|
+| Root docs such as `README.md`, `CONTRIBUTING.md`, or `docs/*.md` | Preview the Markdown and self-review links. |
+| Essays, logs, layouts, includes, or `_config.yml` | `bundle exec jekyll build --strict_front_matter --future` |
+| `_posts/` or `_logs/` content that changes generated indexes | Run the Jekyll build, then expect CI to verify frontmatter, links, and `data/` drift. |
+
+CI also runs the shared `essay-pipeline` and `editorial-standards` repositories
+for frontmatter validation, internal link checks, and generated data drift. If
+CI reports drift in `data/`, regenerate the data artifacts or ask for maintainer
+help in the PR.
 
-Essays use Markdown with YAML frontmatter (title, date, categories, tags, excerpt). Follow the existing essay style: clear prose, specific examples, honest reflection. Filenames follow Jekyll convention: YYYY-MM-DD-slug.md in _posts/.
+## Writing Style
 
-### Commit Messages
+Essays should be clear, specific, and honest about process. Prefer concrete
+examples over abstract claims. Keep filenames in the Jekyll format
+`YYYY-MM-DD-slug.md` when adding a dated post.
 
-- Use imperative mood: "add feature" not "added feature"
-- Keep the title under 72 characters
-- Reference issue numbers when applicable: "fix auth bug (#42)"
-- Keep commits atomic and focused on a single change
+When editing existing essays, preserve the author's voice. Improve clarity
+without flattening the argument.
 
-## Pull Request Process
+## Pull Request Expectations
 
-1. Fill out the PR template with a description of your changes
-2. Reference any related issues
-3. Ensure all CI checks pass
-4. Request review from a maintainer
-5. Address review feedback promptly
+- Explain what changed and why.
+- Link the issue or feedback session when applicable.
+- Summarize the checks you ran.
+- Keep each PR focused on one correction, essay, or documentation improvement.
+- Do not commit secrets, credentials, API keys, tokens, or private data.
 
-PRs should be focused — one feature or fix per PR. Large changes should be
-discussed in an issue first.
+Large changes are welcome, but they should start as an issue so scope and
+review expectations are clear before the work begins.
 
 ## Code of Conduct
 
@@ -92,8 +121,7 @@ Be respectful, constructive, and honest. This project is part of the
 and building in public. We follow the
 [Contributor Covenant](https://www.contributor-covenant.org/).
 
-## Questions?
+## Questions
 
-Open an issue on this repository or start a discussion if discussions are
-enabled. For system-wide questions, see
+Open an issue on this repository. For system-wide questions, see
 [orchestration-start-here](https://github.com/organvm-iv-taxis/orchestration-start-here).

README.md

@@ -14,6 +14,10 @@
 
 > Building in public: the methodology, cross-validation cycle, and lessons learned from coordinating ~79 repositories across 8 GitHub organizations using AI agents as an ensemble of specialized reviewers.
 
+This repository is ORGAN-V's public essay site. The complete dated essay corpus
+lives in `_posts/`, curated long-form essays live in `essays/`, and contributor
+guidance starts in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
 [Introduction](#introduction) | [The Eight-Organ Model](#the-eight-organ-model) | [Methodology](#methodology) | [The Cross-Validation Cycle](#the-cross-validation-cycle) | [Per-Agent Findings](#per-agent-findings) | [Synthesis](#synthesis) | [Simulating Organizational Scale](#simulating-organizational-scale-in-solo-practice) | [Lessons Learned](#lessons-learned) | [Cross-References](#cross-references)
 
 ---

data/cross-references.json

@@ -1,6 +1,6 @@
 {
   "version": "1.1",
-  "updated": "2026-05-29",
+  "updated": "2026-07-06",
   "total": 65,
   "entries": {
     "2026-02-10-building-in-public.md": {

data/essays-index.json

@@ -1,6 +1,6 @@
 {
   "version": "1.1",
-  "updated": "2026-05-29",
+  "updated": "2026-07-06",
   "generated_by": "essay-pipeline indexer v0.3.0",
   "total_essays": 65,
   "total_words": 175691,

data/logs-index.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0",
-  "updated": "2026-05-29",
+  "updated": "2026-07-06",
   "generated_by": "essay-pipeline indexer v0.3.0",
   "total_logs": 458,
   "total_words": 145314,