Understanding Decision States: Draft, Pending, Accepted, Deprecated

Understanding Decision States: Draft, Pending, Accepted, Deprecated

Decisions are the primary unit of authority within Hopsule. Unlike static text or traditional documentation, a decision in Hopsule is an enforceable constraint that carries the weight of organizational judgment. To manage these constraints effectively, every decision follows a structured lifecycle consisting of four distinct states: Draft, Pending, Accepted, and Deprecated.

This article provides an exhaustive guide to these states, explaining how they govern the behavior of the Hopsule ecosystem—from the Hopsule Dashboard to the Hopsule CLI and Hopsule for VS Code. By mastering the decision lifecycle, your team ensures that context is preserved, enforcement is consistent, and organizational memory remains a living, breathing asset rather than a forgotten archive.

Prerequisites

Before managing decision states, ensure you have completed the following:

• An active Hopsule account with "Maintainer" or "Admin" permissions for your project.

• The Hopsule Dashboard open in your browser.

• Hopsule for VS Code installed if you wish to observe real-time enforcement of Accepted decisions.

• A basic understanding of the Hopsule philosophy: "Enforcement is remembrance, not control."

The Decision Lifecycle: A Detailed Walkthrough

The lifecycle of a decision reflects the natural evolution of engineering consensus. It begins with an idea, moves through a period of scrutiny, becomes a binding standard, and eventually matures into a historical reference point.

1. The Draft State: Ideation and Refinement

The Draft state is the incubation phase for organizational judgment. When you first identify a need for a new standard or architectural commitment, you begin in the Draft state. Decisions in this state are private to the creator and are not yet broadcast to the wider team or enforced in development environments.

How to create and manage Drafts:

1. Navigate to the Decisions tab in the Hopsule Dashboard.

2. Click the Create Decision button in the top-right corner.

3. In the creation modal, provide a concise title and a detailed description of the decision.

4. Use Hopper, the built-in AI assistant, to refine your draft. You can prompt Hopper by clicking the Ask Hopper icon within the editor to check for contradictions with existing memories or to suggest improvements based on your team's historical context.

5. Assign relevant tags and categories to ensure the decision is discoverable within the Knowledge Graph.

6. Click Save as Draft.

In the Draft state, the decision is visible only to you and designated collaborators. It will not appear in the hopsule list command in the Hopsule CLI for other team members, nor will it trigger warnings in Hopsule for VS Code. This allows for total freedom to iterate on the reasoning and link relevant Memories—the append-only context entries that explain why this decision is being considered.

2. The Pending State: Review and Consensus

Once a draft is sufficiently refined, it must be moved to the Pending state. This signals to the organization that a decision is ready for formal review. The Pending state is the governance gate where stakeholders can provide feedback, challenge assumptions, and ensure the decision aligns with broader organizational goals.

How to transition to Pending:

1. Open the desired decision in the Hopsule Dashboard.

2. Click the Submit for Review button in the decision header.

3. Optionally, notify specific team members or groups to initiate the review process.

While a decision is Pending, it is visible to the entire team. However, it is not yet "authoritative." This means Hopsule for VS Code will not flag code that contradicts a Pending decision. Instead, the IDE extension will show the decision as "Proposed" in the sidebar tree view, allowing developers to see what changes may be coming without being restricted by them yet. Hopper plays a critical role here by automatically detecting if a Pending decision conflicts with an existing Accepted decision, preventing organizational drift before it happens.

3. The Accepted State: Authority and Enforcement

When a decision is Accepted, it transitions from a proposal to an active constraint. This is the most critical state in Hopsule. Acceptance represents a formal commitment by the team to follow a specific path. Once a decision is Accepted, it is broadcast across the entire Hopsule ecosystem.

How to transition to Accepted:

1. Review the feedback and linked Memories within the Pending decision.

2. Ensure all conflicts identified by Hopper have been resolved.

3. Click the Accept Decision button. This action requires appropriate permissions (typically Admin or Project Lead).

4. Confirm the action in the dialogue box. This timestamped event is recorded in the decision's version history, preserving the moment of commitment.

Impact of the Accepted State:

• Hopsule for VS Code: The extension now actively monitors your codebase. If a developer writes code that contradicts an Accepted decision, Hopsule for VS Code will surface an inline warning. This is not about control; it is about remembrance—reminding the developer of the collective agreement they are part of.

• Hopsule CLI: Running hopsule status will now include this decision in the project’s health report. It will also appear in the interactive TUI dashboard.

• Hopsule MCP: Any AI agents connected via the Hopsule MCP server will receive this decision as part of their context window. The AI becomes context-aware, ensuring its suggestions align with your team's established standards.

• Knowledge Graph: The decision becomes a central node in the Brain, showing its relationships to other decisions and memories.

4. The Deprecated State: Preservation of Context

In Hopsule, we never delete decisions. Deletion is the destruction of organizational memory. Instead, when a decision is no longer relevant—perhaps due to a shift in technology, a change in business requirements, or the adoption of a superior standard—it is moved to the Deprecated state.

How to transition to Deprecated:

1. Select the Accepted decision you wish to retire in the Hopsule Dashboard.

2. Click the Deprecate button.

3. You will be prompted to link a "Superseding Decision" if one exists. This creates a clear lineage of organizational judgment, allowing future developers to trace the evolution of your standards.

4. Provide a final Memory entry explaining the reasoning for the deprecation.

A Deprecated decision is no longer enforced. Hopsule for VS Code will stop surfacing warnings for it, and it will be moved to the "Historical" section of your Context Packs. However, the decision and its associated memories remain searchable and visible in the Knowledge Graph. This ensures that if a similar problem arises in three years, the team can look back and understand why the previous decision was made and why it was eventually abandoned.

Managing States via Hopsule CLI

For developers who prefer the terminal, the Hopsule CLI provides a robust interface for managing decision states. This is particularly useful for integrating decision governance into CI/CD pipelines or local development workflows.

To view the current state of all decisions in your project, use:

To move a decision from Draft to Pending via the CLI:

To accept a decision (requires admin token):

The CLI will provide a summary of the transition, including any linked memories that were updated during the process. This ensures that even when working outside the Dashboard, the rigor of the decision lifecycle is maintained.

Tips and Best Practices

• Always Link Memories: Before moving a decision from Draft to Pending, ensure it has at least one linked Memory. A decision without reasoning is merely a rule; a decision with a Memory is an insight.

• Use Hopper as a Sounding Board: During the Draft phase, ask Hopper: "Does this decision contradict our existing architectural memories?" This prevents the creation of fragmented or conflicting governance.

• Leverage Context Packs (Capsules): When preparing a decision for a new project, you can pull in Deprecated decisions from similar historical projects to avoid repeating past mistakes.

• Enforcement is Remembrance: Remind your team that seeing a warning in VS Code for an Accepted decision is a helpful nudge from the "past self" of the organization, not a bureaucratic hurdle.

• Review Deprecated Decisions Periodically: Use the Knowledge Graph to visualize your Deprecated decisions. This can reveal patterns in how your organization learns and adapts over time.

Troubleshooting Decision States

Related Articles

• Linking Memories to Decisions: Preserving the 'Why'

• Using Hopper to Detect Decision Conflicts

• Configuring Enforcement Levels in Hopsule for VS Code

• Creating and Distributing Context Packs (Capsules)