Skip to content

docs: replace design doc with ADRs#5

Merged
harumiWeb merged 2 commits intomainfrom
docs-organize
Mar 30, 2026
Merged

docs: replace design doc with ADRs#5
harumiWeb merged 2 commits intomainfrom
docs-organize

Conversation

@harumiWeb
Copy link
Copy Markdown
Owner

@harumiWeb harumiWeb commented Mar 30, 2026

Summary

  • replace the legacy docs/design.md with three accepted ADRs covering runtime architecture, bundled core dictionary lifecycle, and release/update policy
  • update README and third-party notices to align with the current runtime dependency and release information
  • record the documentation reorganization scope and completion state in asks/feature_spec.md and asks/todo.md

Verification

  • go test ./...
  • pre-commit hooks: goimports, est, lint

Summary by CodeRabbit

  • Documentation
    • Added status badges to README files for version, license, CI and code-quality visibility.
    • Updated third-party notices to include an additional runtime dependency and license entry.
    • Introduced architecture decision records and task specifications capturing runtime, dictionary lifecycle, and release/update policies; removed the prior large design document and reorganized docs accordingly.

@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 30, 2026

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR reorganizes documentation: it removes a large design doc, adds three ADRs (local-first TUI/CLI, bundled core dictionary lifecycle, release/update policy), adds README badges, records a new runtime dependency, and adds task/spec tracking files.

Changes

Cohort / File(s) Summary
ADR Documentation
docs/adr/0001-local-first-tui-cli-architecture.md, docs/adr/0002-bundled-core-dictionary-lifecycle.md, docs/adr/0003-release-and-update-policy.md
Added three ADRs specifying runtime architecture, bundled core dictionary provenance/lifecycle, and release/update-check operational policy.
README Badge Additions
README.md, README.en.md
Inserted a centered HTML <div> containing status badges (GitHub Release, Go module version, Apache-2.0 license, CI workflow status, Codacy grade).
Specification & Task Tracking
tasks/feature_spec.md, tasks/todo.md
Added a feature-spec outlining the doc reorganization and updated TODOs to record the ADR extraction and cleanup tasks.
License & Dependency Updates
THIRD_PARTY_NOTICES.md
Updated runtime-dependencies section; added github.com/mattn/go-runewidth entry (MIT) with license reference.
Design Document Removal
docs/design.md
Removed the comprehensive design.md (MVP assumptions, architecture, DB schema, command specs, UI/state design, and related content).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 I hopped through docs with gentle paws,

Badges gleam where headings pause.
ADRs planted, old plans laid to rest,
A tidy burrow—organized and blessed.
—the doc-loving rabbit ✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately and concisely summarizes the main change: replacing a legacy design document with three Architecture Decision Records (ADRs).
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs-organize

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

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

Copy link
Copy Markdown

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (3)
docs/adr/0003-release-and-update-policy.md (1)

1-47: Consider using adr-manager skill for ADR creation.

The ADR content is technically accurate (verified against code snippets showing DefaultTTL=24h, DefaultTimeout=1.5s, EITANGO_DISABLE_UPDATE_CHECK env var, first-run suppression logic, and silent error handling). However, the repository guideline states to use the adr-manager skill when editing ADRs.

While this guideline specifically mentions "editing" (編集), and these are new ADRs being created rather than edited, consider whether the adr-manager skill should also be used for ADR creation to maintain consistency in ADR management practices.

Based on learnings: 設計判断やトレードオフは docs/adr/ に、現行の内部仕様や制約は docs/specs/ に移すこと / ADR を編集する場合は adr-manager skill を使うこと

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/0003-release-and-update-policy.md` around lines 1 - 47, The ADR was
created without using the repository's adr-manager workflow; update
docs/adr/0003-release-and-update-policy.md to follow the repo guideline by
either recreating or registering this ADR via the adr-manager skill (or add a
brief note in the ADR header indicating an approved exception), referencing the
adr-manager process so the ADR is tracked consistently; ensure the ADR
metadata/header includes the adr-manager identifier or exception note to match
other ADRs.
docs/adr/0002-bundled-core-dictionary-lifecycle.md (1)

1-52: Consider using adr-manager skill for ADR creation.

The ADR content is technically accurate (verified against code snippets showing ValidateCoreEntries validation, CoreWordsVersion constant, source separation via WordSourceCore/"import:" constants, and selective reset behavior). However, the repository guideline states to use the adr-manager skill when editing ADRs.

While this guideline specifically mentions "editing" (編集), and these are new ADRs being created rather than edited, consider whether the adr-manager skill should also be used for ADR creation to maintain consistency in ADR management practices.

Based on learnings: 設計判断やトレードオフは docs/adr/ に、現行の内部仕様や制約は docs/specs/ に移すこと / ADR を編集する場合は adr-manager skill を使うこと

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/0002-bundled-core-dictionary-lifecycle.md` around lines 1 - 52, The
ADR was created directly but repository guidelines require using the adr-manager
tool for ADR edits (and likely for creation to keep consistency); update the
process for this ADR by reauthoring or registering it through the adr-manager
workflow and/or CLI so metadata, changelog, and management records are
consistent with other ADRs (ensure
docs/adr/0002-bundled-core-dictionary-lifecycle.md is generated/registered via
adr-manager and reference the adr-manager usage in the ADR header or repo
CONTRIBUTING notes so future ADRs and edits use adr-manager).
docs/adr/0001-local-first-tui-cli-architecture.md (1)

1-49: Consider using adr-manager skill for ADR creation.

The ADR appropriately documents architectural design decisions about the local-first TUI/CLI runtime structure. However, the repository guideline states to use the adr-manager skill when editing ADRs.

While this guideline specifically mentions "editing" (編集), and these are new ADRs being created rather than edited, consider whether the adr-manager skill should also be used for ADR creation to maintain consistency in ADR management practices.

Based on learnings: 設計判断やトレードオフは docs/adr/ に、現行の内部仕様や制約は docs/specs/ に移すこと / ADR を編集する場合は adr-manager skill を使うこと

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/adr/0001-local-first-tui-cli-architecture.md` around lines 1 - 49, The
ADR (ADR-0001 in docs/adr/0001-local-first-tui-cli-architecture.md) was added
directly but repository conventions require using the adr-manager skill for ADR
lifecycle actions; update this change by recreating or moving ADR-0001 using the
adr-manager workflow (use the adr-manager tool/skill to create the ADR entry
instead of hand-editing the file), ensure the ADR metadata and status fields
match the current content, and remove the manual file edit so the adr-manager
becomes the authoritative source for this ADR going forward.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.en.md`:
- Around line 9-14: The Go module version badge URL uses inconsistent lowercase
repository casing ("harumiweb/eitango") while the other badges use
"harumiWeb/eitango"; update the Go module badge URL string to match the exact
"harumiWeb/eitango" casing so all badge URLs are uniform (change the segment in
the Go module version badge URL that currently reads harumiweb/eitango to
harumiWeb/eitango).

In `@README.md`:
- Around line 9-14: Update the badge URLs so the repository name casing is
consistent by replacing the lowercase occurrence "harumiweb/eitango" in the Go
module version badge URL with "harumiWeb/eitango" to match the other badges
(look for the markdown image/link that contains
"https://img.shields.io/github/go-mod/go-version/harumiweb/eitango" and change
it to use "harumiWeb/eitango"); ensure all other badge URLs (e.g., the GitHub
Release badge and any other shields) use the exact same "harumiWeb/eitango"
casing.

---

Nitpick comments:
In `@docs/adr/0001-local-first-tui-cli-architecture.md`:
- Around line 1-49: The ADR (ADR-0001 in
docs/adr/0001-local-first-tui-cli-architecture.md) was added directly but
repository conventions require using the adr-manager skill for ADR lifecycle
actions; update this change by recreating or moving ADR-0001 using the
adr-manager workflow (use the adr-manager tool/skill to create the ADR entry
instead of hand-editing the file), ensure the ADR metadata and status fields
match the current content, and remove the manual file edit so the adr-manager
becomes the authoritative source for this ADR going forward.

In `@docs/adr/0002-bundled-core-dictionary-lifecycle.md`:
- Around line 1-52: The ADR was created directly but repository guidelines
require using the adr-manager tool for ADR edits (and likely for creation to
keep consistency); update the process for this ADR by reauthoring or registering
it through the adr-manager workflow and/or CLI so metadata, changelog, and
management records are consistent with other ADRs (ensure
docs/adr/0002-bundled-core-dictionary-lifecycle.md is generated/registered via
adr-manager and reference the adr-manager usage in the ADR header or repo
CONTRIBUTING notes so future ADRs and edits use adr-manager).

In `@docs/adr/0003-release-and-update-policy.md`:
- Around line 1-47: The ADR was created without using the repository's
adr-manager workflow; update docs/adr/0003-release-and-update-policy.md to
follow the repo guideline by either recreating or registering this ADR via the
adr-manager skill (or add a brief note in the ADR header indicating an approved
exception), referencing the adr-manager process so the ADR is tracked
consistently; ensure the ADR metadata/header includes the adr-manager identifier
or exception note to match other ADRs.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 803b0892-3418-4c80-aebc-3ad3754244ab

📥 Commits

Reviewing files that changed from the base of the PR and between c96301e and 7f5088e.

📒 Files selected for processing (9)
  • README.en.md
  • README.md
  • THIRD_PARTY_NOTICES.md
  • docs/adr/0001-local-first-tui-cli-architecture.md
  • docs/adr/0002-bundled-core-dictionary-lifecycle.md
  • docs/adr/0003-release-and-update-policy.md
  • docs/design.md
  • tasks/feature_spec.md
  • tasks/todo.md
💤 Files with no reviewable changes (1)
  • docs/design.md

@harumiWeb harumiWeb merged commit 43cb87b into main Mar 30, 2026
6 of 7 checks passed
@harumiWeb harumiWeb deleted the docs-organize branch March 30, 2026 12:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant