docs: refactor gaia ADRs

CONTRIBUTING.md

@@ -6,6 +6,7 @@
     - [Ease of reviewing](#ease-of-reviewing)
     - [Workflow](#workflow)
   - [Project Board](#project-board)
+  - [Architecture Decision Records (ADR)](#architecture-decision-records-adr)
   - [Development Procedure](#development-procedure)
     - [Testing](#testing)
     - [Pull Requests](#pull-requests)
@@ -99,6 +100,14 @@ We use self-organizing principles to coordinate and collaborate across organizat
 
 The developers work in sprints, which are available in a [GitHub Project](https://github.com/orgs/cosmos/projects/28/views/2). 
 
+## Architecture Decision Records (ADR)
+
+When proposing an architecture decision for Gaia, please start by opening an [issue](https://github.com/cosmos/gaia/issues/new/choose) or a [discussion](https://github.com/cosmos/gaia/discussions/new) with a summary of the proposal. Once the proposal has been discussed and there is rough alignment on a high-level approach to the design, you may either start development, or write an ADR.
+
+If your architecture decision is a simple change, you may contribute directly without writing an ADR. However, if you are proposing a significant change, please include a corresponding ADR.
+
+To create an ADR, follow the [template](./docs/architecture/adr-template.md) and [doc](./docs/architecture/README.md). If you would like to see examples of how these are written, please refer to the current [ADRs](https://github.com/cosmos/gaia/tree/main/docs/architecture).
+
 ## Development Procedure
 
 `main` must be stable, include only completed features and never fail `make lint`, `make run-tests`, or `make build/install`.

docs/architecture/PROCESS.md

@@ -0,0 +1,57 @@
+# ADR Creation Process
+
+1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md`
+2. Create a draft Pull Request and solicit input from the stewarding team, if you want to get an early feedback.
+3. Make sure that the problem, the context and a recommended solution is clear and well documented. Be sure to document alternate solution spaces and give reasons why they have been discarded.
+4. Add an entry to a list in the README file [Table of Contents](./README.md#adr-table-of-contents).
+5. Create a Pull Request to propose a new ADR.
+
+## ADR life cycle
+
+ADR creation is an **iterative** process. Instead of trying to solve all decisions in a single ADR pull request, we MUST firstly understand the problem and collect feedback through a GitHub Issue.
+
+1. Every proposal SHOULD start with a new GitHub Issue or be a result of existing Issues. The Issue should contain just a brief proposal summary.
+
+2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`.
+
+3. An ADR doesn't have to arrive to `main` with an _accepted_ status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a _proposed_ status. It's preferable to have an iterative approach rather than long, not merged Pull Requests.
+
+4. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue.
+
+5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it.
+
+6. Merged ADRs SHOULD NOT be deleted.
+
+### ADR status
+
+Status has two components:
+
+```text
+{CONSENSUS STATUS} {IMPLEMENTATION STATUS}
+```
+
+IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`.
+
+#### Consensus Status
+
+```mermaid
+flowchart TD
+    A[DRAFT] --> B[PROPOSED]
+    B --> C[LAST CALL YYYY-MM-DD]
+    B --> D[ABANDONED]
+    C --> E[ACCEPTED or REJECTED]
+    E --> F[SUPERSEDED by ADR-xxx]
+```
+
+* `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form.
+* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreement yet.
+* `LAST CALL <date for the last call>`: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze.
+* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design.
+* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so.
+* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR.
+* `ABANDONED`: the ADR is no longer pursued by the original authors.
+
+## Language used in ADR
+
+* The context/background should be written in the present tense.
+* Avoid using a first, personal form.

docs/architecture/README.md

@@ -0,0 +1,64 @@
+<!--
+order: 1
+parent:
+  title: Architecture Decision Records (ADR)
+  order: 10
+-->
+
+# Architecture Decision Records (ADR)
+
+This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub.
+
+An Architectural Decision (**AD**) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
+An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality.
+An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM).
+
+You can read more about the ADR concept [here](https://adr.github.io/).
+
+## Rationale
+
+ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions.
+An ADR should provide:
+
+- Context on the relevant goals and the current state
+- Proposed changes to achieve the goals
+- Summary of pros and cons
+- Discarded solution spaces and why they were discarded
+- References
+- Changelog
+
+Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and
+justification for a change in architecture, or for the architecture of something
+new. The spec is much more compressed and streamlined summary of everything as
+it stands today.
+
+If recorded decisions turn out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match.
+
+## Creating new ADR
+
+Read about the [PROCESS](./PROCESS.md).
+
+### Use RFC 2119 Keywords
+
+When writing ADRs, follow the same best practices for writing RFCs. 
+When writing RFCs, key words are used to signify the requirements in the specification. 
+These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. 
+They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+
+## ADR Table of Contents
+
+### Accepted
+
+- n/a
+
+### Proposed
+
+- n/a
+
+### Draft
+
+- n/a
+
+### Rejected
+
+- [ADR 001: Interchain Accounts](./adr-001-interchain-accounts.md)

docs/readiness/adr-001-interchain-accounts.md → docs/architecture/adr-001-interchain-accounts.md

@@ -2,26 +2,19 @@
 order: 2
 -->
 
----
-
-ADR: 001
-Title: Interchain Accounts
-Status: Draft Implements
-Category: Feature
-Author: Sean King & Damian Nolan
-Created: 2022-01-19
-Mdified: 2022-01-19
-Requires: Cosmos-SDK, go-ibc
-Required-By: mauth
-Implements: Interchain Accounts
----
-
 # ADR 001: Interchain Accounts
 
 ## Changelog
 
 - 2022-02-04: added content
 - 2022-01-19: init
+- 2023-06-28: mark as rejected
+
+## Status
+
+REJECTED Not Implemented
+
+**Reason:** The IBC team decided to integrate this functionality directly into their codebase and maintain it, because multiple users require it. 
 
 ## Abstract
 
@@ -98,4 +91,4 @@ There are future releases of Interchain Accounts which are expected to be backwa
 ## Additional Research & References
 
 - [Why Interchain Accounts Change Everything for Cosmos Interoperability](https://medium.com/chainapsis/why-interchain-accounts-change-everything-for-cosmos-interoperability-59c19032bf11)
-- [Interchain Account Auth Module Demo Repo](https://github.com/cosmos/interchain-accounts)
+- [Interchain Account Auth Module Demo Repo](https://github.com/cosmos/interchain-accounts)

docs/architecture/adr-template.md

@@ -0,0 +1,58 @@
+<!--
+order: false
+-->
+
+# ADR {ADR-NUMBER}: {TITLE}
+
+## Changelog
+
+- {date}: {changelog}
+
+## Status
+
+{DRAFT | PROPOSED} Not Implemented
+
+> Please have a look at the [PROCESS](./PROCESS.md#adr-status) page.
+> Use DRAFT if the ADR is in a draft stage (draft PR) or PROPOSED if it's in review.
+
+## Abstract
+
+> "If you can't explain it simply, you don't understand it well enough." Provide
+> a simplified and layman-accessible explanation of the ADR.
+> A short (~200 word) description of the issue being addressed.
+
+## Context
+
+> This section contains all the context one needs to understand the current state, and why there is a problem. 
+> It should be as succinct as possible and introduce the high level idea behind the solution. 
+> The language in this section is value-neutral. It is simply describing facts.
+
+## Decision
+
+> This section explains all of the details of the proposed solution, including implementation details.
+It should also describe affects / corollary items that may need to be changed as a part of this.
+If the proposed change will be large, please also indicate a way to do the change to maximize ease of review.
+(e.g. the optimal split of things to do between separate PR's)
+
+## Consequences
+
+> This section describes the consequences, after applying the decision. 
+> All consequences should be summarized here, not just the "positive" ones.
+
+### Positive
+
+> {positive consequences}
+
+### Negative
+
+> {negative consequences}
+
+### Neutral
+
+> {neutral consequences}
+
+## References
+
+> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here!
+
+* {reference link}