Docs: retire Neo4j journaling workflow

[flyingrobots]

Summary

• remove Neo4j journaling references from onboarding/workflow docs
• point contributors to execution-plan and decision-log for timeline updates
• retune scaffolding script prompts for doc-based logging

Testing

• not run (documentation-only)

[coderabbitai]

Summary by CodeRabbit

• Documentation

  • Simplified decision logging workflow with standardized Markdown-based approach for improved accessibility and consistency.
  • Added guidance for recording demo outcomes with labeled prefixes to enhance searchability.

• Chores

  • Implemented automated CI check to ensure documentation stays synchronized when code changes occur.

Walkthrough

Replaces Neo4j-centered logging references with a unified file-based decision-log workflow across documentation and scaffold prompts, and adds a CI "Docs Guard" job that enforces updates to docs/execution-plan.md and docs/decision-log.md when non-doc files change.

Changes

Cohort / File(s)	Summary
Documentation checklist & plans docs/codex-implementation-checklist.md, docs/phase1-plan.md, docs/rmg-demo-roadmap.md	Replaced Neo4j/echo-devlog references with docs/decision-log.md; updated checklist text and demo outcome formatting to require Demo <n> — … prefixes.
Execution plan docs/execution-plan.md	Reworked pre-work, during-work, post-work, tooling/docs, and table captions to use docs/decision-log.md for journaling, runtime updates, and file/commit references instead of Neo4j IDs.
Scaffold script prompts scripts/scaffold-community.sh	Updated prompt texts: PROJECT_TAG from "Project tag for Neo4j logs" → "Project tag for timeline notes"; DEVLOG_THREAD from "Devlog thread name" → "Devlog document or label"; SPEC_THREAD from "Spec thread name" → "Spec document or label".
CI enforcement .github/workflows/ci.yml	Added "Docs Guard" job that detects changed files in PRs, exits early for doc-only changes, and fails the job unless docs/execution-plan.md and docs/decision-log.md are updated when non-doc files are modified.
Decision log guidance docs/decision-log.md	Added guidance to prefix demo outcomes in the Decision column with Demo <number> — … to improve discoverability.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant Git as GitHub PR
    participant CI as Docs Guard (CI)
    participant Files as Repo files
    rect #f0f9ff
      Dev->>Git: Open PR
      Git->>CI: Trigger Docs Guard job
    end
    CI->>Files: Compute changed file list
    alt Only documentation changed
      CI->>CI: Exit success (no docs gating)
      CI-->>Dev: CI passes
    else Non-doc files changed
      CI->>Files: Check `docs/execution-plan.md` and `docs/decision-log.md`
      alt Both updated
        CI-->>Dev: CI passes
      else Missing updates
        CI-->>Dev: CI fails with list of changed files
      end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Potential attention targets:

• .github/workflows/ci.yml — confirm diff detection logic and expected path filters.
• docs/execution-plan.md — verify wording consistency where Neo4j references were removed.
• docs/decision-log.md — ensure guidance and example match other docs and templates.
• scripts/scaffold-community.sh — confirm prompt text changes don't affect downstream parsing or automation.

Poem

📝 A switch from threads to tidy logs,
Markdown now cradles demo thoughts,
CI watches, gates the flow,
Decisions penned where searches go. ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title "Docs: retire Neo4j journaling workflow" directly and accurately reflects the core change across the entire changeset. All six modified files involve systematically removing Neo4j references and replacing them with a documentation-based workflow centered on docs/decision-log.md and docs/execution-plan.md. The title is concise, specific, and immediately conveys the main objective without vagueness or noise.
Description Check	✅ Passed	The PR description accurately captures the three key aspects of the changeset: removing Neo4j journaling references from documentation, redirecting contributors to use execution-plan and decision-log for updates, and retuning the scaffolding script prompts. The description is directly related to the modifications present in the changeset and provides sufficient context about the intent without unnecessary verbosity. The note about testing being documentation-only is also appropriate and transparent.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch echo/remove-neo4j-logging

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7111876 and ee19ec3.

📒 Files selected for processing (5)

• .github/workflows/ci.yml (1 hunks)
• docs/decision-log.md (1 hunks)
• docs/execution-plan.md (4 hunks)
• docs/phase1-plan.md (1 hunks)
• docs/rmg-demo-roadmap.md (1 hunks)

🧰 Additional context used

🧠 Learnings (4)

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Summarize intent, work done, and next steps in Neo4j entries

Applied to files:

• docs/execution-plan.md

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Follow cadence for Neo4j logging: start, milestones/decisions, external references, and session finish with outcome + next steps

Applied to files:

• docs/execution-plan.md

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Use Neo4j threads: echo-devlog for daily journal/decisions/blockers and echo-spec for high-level proposals

Applied to files:

• docs/execution-plan.md

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Document Ruthlessly: record meaningful design choices in docs/ or as a Neo4j journal entry tagged "Echo"

Applied to files:

• docs/execution-plan.md

🔇 Additional comments (7)

docs/decision-log.md (1)

3-3: ✅ Schema defined—resolves prior critical blocker on vague tagging.

The guidance line now explicitly specifies the demo-entry prefix format (Demo <number> — …), directly addressing the prior review's concern that contributors would "invent their own format" due to undefined schema. Coupled with the example in docs/phase1-plan.md (line 112), this is unambiguous and enforces consistency.

docs/rmg-demo-roadmap.md (1)

75-75: ✅ Specificity restored—docs/decision-log.md now explicit.

Prior reviewer flagged line 75 as punting to a vague "documentation workflow" while every other file in the PR explicitly names docs/decision-log.md. This fix makes it consistent and leaves no ambiguity about where demo outcomes should be logged.

docs/phase1-plan.md (1)

112-112: ✅ Critical issue resolved: tagging schema now explicitly defined with concrete example.

Prior review (Linus tone) flagged the instruction to "tag entries with the relevant demo" as completely undefined, warning that contributors would "invent their own format" without explicit schema. This fix directly addresses that by specifying the exact format (Demo <number> — …) with a worked example (Demo 2 — Timeline hash verified), tied to the guidance line in docs/decision-log.md. No ambiguity. Enforceable.

.github/workflows/ci.yml (1)

56-86: ✅ Docs Guard CI job directly resolves critical enforcement blocker.

Prior review (Linus tone) said: "Documentation sync directive needs enforcement or it's theater. Contributors will skip this... You need [a CI job that enforces both files updated]." This implementation does exactly that:

• Runs only on pull_request (no noise on push)
• Correctly identifies non-doc file changes
• Fails fast if either docs/execution-plan.md or docs/decision-log.md is missing from the changeset when code changes
• Uses exact-match grep (-Fx) to avoid false positives

The logic is sound: docs-only PRs pass, code-only PRs fail (both docs must be updated), and mixed PRs only pass when both doc files touched. This has teeth. Contributors can no longer skip documentation as an afterthought.

docs/execution-plan.md (3)

9-16: ✅ Dual-logging hierarchy now explicit and unambiguous.

Prior review flagged the relationship between local "Decision Log (High-Level)" table and docs/decision-log.md as confused, with wishy-washy "when appropriate" and "or" language that created false choice. This fix clarifies:

• Line 13 calls docs/decision-log.md the (canonical log) — singular authority.
• Line 16 requires "full entry captured in docs/decision-log.md" — no ambiguity about destination.
• Line 96 reframes local table as convenience summary ("Keep this table updated for quick reference") — not the source of truth.

Prior confusion: contributors didn't know which log mattered. Now they do.

---

96-96: ✅ Practical guidance teaches what "meaningful" entries look like.

The note to include "file references or commit hashes when useful" grounds the documentation discipline in specifics rather than hand-waving. Contributes understand that their log entries should be tied to concrete artifacts (commit SHAs, file paths), not vague generalizations. Pairs well with the Demo <number> — … schema defined elsewhere in the PR.

---

112-112: ✅ Daily sync discipline now has enforcement teeth via CI Docs Guard.

The instruction to update both docs/execution-plan.md and docs/decision-log.md no longer floats as theater. The new Docs Guard CI job (lines 56–86 in .github/workflows/ci.yml) now fails PRs if either file is missing when code changes. Contributors can no longer skip documentation as an afterthought. This resolves the prior critical review's demand for enforcement.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 54d6d27 and 7111876.

⛔ Files ignored due to path filters (2)

• AGENTS.md is excluded by !*.md
• CONTRIBUTING.md is excluded by !*.md

📒 Files selected for processing (5)

• docs/codex-implementation-checklist.md (1 hunks)
• docs/execution-plan.md (4 hunks)
• docs/phase1-plan.md (1 hunks)
• docs/rmg-demo-roadmap.md (1 hunks)
• scripts/scaffold-community.sh (1 hunks)

🧰 Additional context used

🧠 Learnings (4)

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Follow cadence for Neo4j logging: start, milestones/decisions, external references, and session finish with outcome + next steps

Applied to files:

• docs/codex-implementation-checklist.md
• docs/execution-plan.md

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Summarize intent, work done, and next steps in Neo4j entries

Applied to files:

• docs/execution-plan.md

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Use Neo4j threads: echo-devlog for daily journal/decisions/blockers and echo-spec for high-level proposals

Applied to files:

• docs/execution-plan.md

📚 Learning: 2025-10-25T13:22:15.193Z

Learnt from: CR
PR: flyingrobots/echo#0
File: AGENTS.md:0-0
Timestamp: 2025-10-25T13:22:15.193Z
Learning: Document Ruthlessly: record meaningful design choices in docs/ or as a Neo4j journal entry tagged "Echo"

Applied to files:

• docs/execution-plan.md

🔇 Additional comments (3)

docs/codex-implementation-checklist.md (1)

60-60: Solid substitution—no issues here.

Straightforward swap with improved clarity. The "(optional)" qualifier appropriately reflects its status as a follow-up task, not a blocker.

scripts/scaffold-community.sh (1)

32-34: Prompt text improvements are appropriate and clear.

Terminology updated from Neo4j-centric ("thread") to workflow-agnostic ("document or label"). No functional changes; purely UX improvement. Clean and consistent across all three prompts.

docs/execution-plan.md (1)

96-96: Comment clarification is solid.

Replacing Neo4j message IDs with file references/commit hashes is practical and traceable. Good change.