thuanle/claw-email
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adopt ADR workflow for durable technical decisions and keep agent planning docs out of implementation PRs #14

New Issue
Closed
opened 2026-04-28 05:32:52 +07:00 by codex · 0 comments
codex commented 2026-04-28 05:32:52 +07:00
Collaborator
Copy Link
Copy Source

Summary

PR #13 raised a valid documentation need: some technical decisions are worth keeping in the repository, but docs/superpowers/** plan/spec files are agent execution artifacts, not durable project records.

We should add an ADR workflow so future PRs can preserve important architecture decisions without bundling temporary agent planning documents into product-change PRs.

Why this issue exists

  • docs/superpowers/plans/** contains implementation checklists and agent-specific instructions.
  • docs/superpowers/specs/** may capture useful reasoning, but in current form they are still tied to execution flow rather than stable repository policy.
  • Reviewer guidance currently has no explicit rule for when to keep a design note, when to convert it to ADR, and when to reject it as scope creep.

Proposed scope

  1. Add an official ADR location and README, for example docs/adr/README.md.
  2. Move durable decision records out of docs/superpowers/** and into docs/adr/**.
  3. Update AGENT.md and repo skills so developers/reviewers know:
    • temporary plan/spec docs stay out of implementation PRs
    • durable architectural decisions go into ADRs
    • reviewers should accept ADRs when they are directly tied to the change and are written as repository records rather than agent artifacts

Proposed docs/adr/README.md

# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for durable technical decisions in this repository.

## Purpose

ADRs capture cross-cutting or behavior-defining decisions that future contributors need to preserve.

Use an ADR when a change introduces or locks in a decision such as:

- runtime behavior that future work must preserve
- repository-wide technical policy
- architecture or integration contracts
- storage or threading semantics
- quality gate or workflow policy

Do not use ADRs for:

- temporary implementation plans
- agent execution checklists
- one-off debugging notes
- PR-local task breakdowns

## Format

Each ADR is a markdown file with YAML frontmatter.

```md
---
type: ADR
id: "NNNN"
title: "Short decision title"
status: active
date: YYYY-MM-DD
---

## Context

Why does this decision need to exist now?

## Decision

**State the decision clearly in one or two sentences.**

## Options considered

- **Option A** (chosen): description with pros and cons
- **Option B**: description with pros and cons
- **Option C**: description with pros and cons

## Consequences

What becomes easier?
What becomes harder?
What risks were accepted?
What would trigger re-evaluation?

## Advice

Optional. Capture important external input or review notes.

Rules

  • One decision per file.
  • Name files NNNN-short-kebab-title.md.
  • Once active, do not rewrite an ADR's meaning later. Supersede it with a new ADR instead.
  • Keep the index below aligned with the current files in this directory.
  • Do not keep placeholder or mock entries in the index.

Index

ID Title Status 

## Proposed ADR draft for the threading decision
Suggested file: `docs/adr/0001-imap-thread-resolution.md`

```md
---
type: ADR
id: "0001"
title: "IMAP thread resolution prefers In-Reply-To and falls back to References"
status: active
date: 2026-04-28
---

## Context

The IMAP ingress flow stores a `thread_id` before dispatching work to OpenClaw. Previously the bridge only used `In-Reply-To` to find a parent task. Some valid email clients preserve thread ancestry through `References` even when `In-Reply-To` is absent. In those cases, the bridge created a new `thread_id`, which broke conversation continuity and downstream session reuse.

This decision needs to be durable because future refactors of mail parsing, dispatch, or storage must preserve the same thread-resolution behavior.

## Decision

The bridge resolves parent thread linkage by trying `In-Reply-To` first. If no parent task is found, it falls back to `References`, scanning message IDs from last to first and using the first match found in the database. If neither header yields a known parent, the message's own `message_id` becomes the new `thread_id`.

## Options considered

- **Use `In-Reply-To` first, then `References` last-to-first** (chosen): preserves existing behavior, matches common email ancestry ordering, and favors the most recent known parent.
- **Use only `In-Reply-To`**: simpler, but breaks valid threads when clients omit `In-Reply-To`.
- **Search `References` from first to last**: may attach to an older ancestor even when a more recent known parent exists.
- **Normalize all thread linkage into a more complex conversation graph**: more flexible, but out of scope for the current bridge behavior.

## Consequences

Thread continuity is improved for replies that rely on `References`.
Future contributors have an explicit behavioral contract for threading semantics.
Mail parsing changes must preserve the header precedence and reverse scan behavior unless a new ADR supersedes this one.
The current approach still depends on existing message IDs being present in the database; if upstream behavior changes significantly, this decision may need reevaluation.

## Advice

If a future change wants different precedence rules or deeper conversation reconstruction, create a new ADR rather than silently changing this behavior.

Proposed AGENT.md changes

Add a repository documentation rule near Workflow/Review sections:

  • Durable architecture or behavior decisions belong in docs/adr/**, not docs/superpowers/**.
  • docs/superpowers/** is for agent execution artifacts and should not be merged as part of product implementation PRs unless the user explicitly asks for that output to be versioned.
  • If a PR needs a lasting technical rationale, author an ADR or repo-sanctioned design note instead.
  • Reviewer should treat temporary plan/spec docs as scope creep, but should allow ADRs that directly document the accepted behavior of the change.

Proposed skill updates

validate-issue

  • When locking Final Requirements, add an explicit note when the change likely needs a durable ADR.
  • Distinguish between implementation scope and documentation-of-decision scope.

do-task

  • If Final Requirements call for durable technical documentation, create/update docs/adr/** rather than committing docs/superpowers/** planning artifacts.
  • Do not include agent execution plans in the implementation PR.

review-pr

  • Continue failing PRs for unrelated or temporary process artifacts.
  • Explicitly allow docs/adr/** when it records a direct, durable decision tied to the issue scope.
  • When rejecting docs, explain whether the content should be deleted entirely or rewritten as an ADR.

Acceptance criteria

  • Repo has an official ADR location and README with no mock index entries.
  • Repo workflow documents explain when ADRs are required and when plan/spec docs are not mergeable.
  • Reviewer and developer skills align on ADR vs plan/spec treatment.
  • A follow-up ADR can be used for PR #13's threading decision.
## Summary PR #13 raised a valid documentation need: some technical decisions are worth keeping in the repository, but `docs/superpowers/**` plan/spec files are agent execution artifacts, not durable project records. We should add an ADR workflow so future PRs can preserve important architecture decisions without bundling temporary agent planning documents into product-change PRs. ## Why this issue exists - `docs/superpowers/plans/**` contains implementation checklists and agent-specific instructions. - `docs/superpowers/specs/**` may capture useful reasoning, but in current form they are still tied to execution flow rather than stable repository policy. - Reviewer guidance currently has no explicit rule for when to keep a design note, when to convert it to ADR, and when to reject it as scope creep. ## Proposed scope 1. Add an official ADR location and README, for example `docs/adr/README.md`. 2. Move durable decision records out of `docs/superpowers/**` and into `docs/adr/**`. 3. Update `AGENT.md` and repo skills so developers/reviewers know: - temporary plan/spec docs stay out of implementation PRs - durable architectural decisions go into ADRs - reviewers should accept ADRs when they are directly tied to the change and are written as repository records rather than agent artifacts ## Proposed `docs/adr/README.md` ```md # Architecture Decision Records This directory contains Architecture Decision Records (ADRs) for durable technical decisions in this repository. ## Purpose ADRs capture cross-cutting or behavior-defining decisions that future contributors need to preserve. Use an ADR when a change introduces or locks in a decision such as: - runtime behavior that future work must preserve - repository-wide technical policy - architecture or integration contracts - storage or threading semantics - quality gate or workflow policy Do not use ADRs for: - temporary implementation plans - agent execution checklists - one-off debugging notes - PR-local task breakdowns ## Format Each ADR is a markdown file with YAML frontmatter. ```md --- type: ADR id: "NNNN" title: "Short decision title" status: active date: YYYY-MM-DD --- ## Context Why does this decision need to exist now? ## Decision **State the decision clearly in one or two sentences.** ## Options considered - **Option A** (chosen): description with pros and cons - **Option B**: description with pros and cons - **Option C**: description with pros and cons ## Consequences What becomes easier? What becomes harder? What risks were accepted? What would trigger re-evaluation? ## Advice Optional. Capture important external input or review notes. ``` ## Rules - One decision per file. - Name files `NNNN-short-kebab-title.md`. - Once active, do not rewrite an ADR's meaning later. Supersede it with a new ADR instead. - Keep the index below aligned with the current files in this directory. - Do not keep placeholder or mock entries in the index. ## Index | ID | Title | Status | |----|-------|--------| ``` ## Proposed ADR draft for the threading decision Suggested file: `docs/adr/0001-imap-thread-resolution.md` ```md --- type: ADR id: "0001" title: "IMAP thread resolution prefers In-Reply-To and falls back to References" status: active date: 2026-04-28 --- ## Context The IMAP ingress flow stores a `thread_id` before dispatching work to OpenClaw. Previously the bridge only used `In-Reply-To` to find a parent task. Some valid email clients preserve thread ancestry through `References` even when `In-Reply-To` is absent. In those cases, the bridge created a new `thread_id`, which broke conversation continuity and downstream session reuse. This decision needs to be durable because future refactors of mail parsing, dispatch, or storage must preserve the same thread-resolution behavior. ## Decision The bridge resolves parent thread linkage by trying `In-Reply-To` first. If no parent task is found, it falls back to `References`, scanning message IDs from last to first and using the first match found in the database. If neither header yields a known parent, the message's own `message_id` becomes the new `thread_id`. ## Options considered - **Use `In-Reply-To` first, then `References` last-to-first** (chosen): preserves existing behavior, matches common email ancestry ordering, and favors the most recent known parent. - **Use only `In-Reply-To`**: simpler, but breaks valid threads when clients omit `In-Reply-To`. - **Search `References` from first to last**: may attach to an older ancestor even when a more recent known parent exists. - **Normalize all thread linkage into a more complex conversation graph**: more flexible, but out of scope for the current bridge behavior. ## Consequences Thread continuity is improved for replies that rely on `References`. Future contributors have an explicit behavioral contract for threading semantics. Mail parsing changes must preserve the header precedence and reverse scan behavior unless a new ADR supersedes this one. The current approach still depends on existing message IDs being present in the database; if upstream behavior changes significantly, this decision may need reevaluation. ## Advice If a future change wants different precedence rules or deeper conversation reconstruction, create a new ADR rather than silently changing this behavior. ``` ## Proposed `AGENT.md` changes Add a repository documentation rule near Workflow/Review sections: - Durable architecture or behavior decisions belong in `docs/adr/**`, not `docs/superpowers/**`. - `docs/superpowers/**` is for agent execution artifacts and should not be merged as part of product implementation PRs unless the user explicitly asks for that output to be versioned. - If a PR needs a lasting technical rationale, author an ADR or repo-sanctioned design note instead. - Reviewer should treat temporary plan/spec docs as scope creep, but should allow ADRs that directly document the accepted behavior of the change. ## Proposed skill updates ### `validate-issue` - When locking Final Requirements, add an explicit note when the change likely needs a durable ADR. - Distinguish between implementation scope and documentation-of-decision scope. ### `do-task` - If Final Requirements call for durable technical documentation, create/update `docs/adr/**` rather than committing `docs/superpowers/**` planning artifacts. - Do not include agent execution plans in the implementation PR. ### `review-pr` - Continue failing PRs for unrelated or temporary process artifacts. - Explicitly allow `docs/adr/**` when it records a direct, durable decision tied to the issue scope. - When rejecting docs, explain whether the content should be deleted entirely or rewritten as an ADR. ## Acceptance criteria - Repo has an official ADR location and README with no mock index entries. - Repo workflow documents explain when ADRs are required and when plan/spec docs are not mergeable. - Reviewer and developer skills align on ADR vs plan/spec treatment. - A follow-up ADR can be used for PR #13's threading decision.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
claudecode codex opencode thuanle
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: thuanle/claw-email#14