Creating a New Decision

Decisions in Hopsule are the fundamental units of organizational judgment that govern your engineering team's future. This guide provides an exhaustive walkthrough for establishing these enforceable constraints, ensuring every commitment is backed by context and preserved within your team's collective memory to prevent the erosion of technical standards over time.

Creating a decision is more than just recording a choice; it is an act of governance. By formalizing a decision within the Hopsule Dashboard or via the Hopsule CLI, you are creating a persistent reference point that Hopper can use for advisory context and Hopsule for VS Code can use for real-time enforcement. This article covers the manual creation process, AI-assisted drafting with Hopper, and command-line workflows.

Prerequisites

Before you begin creating a new decision, ensure you have the following in place to maintain the integrity of your governance layer:

• Active Organization and Project: You must be logged into the Hopsule Dashboard and have a project selected where the decision will reside.

• User Permissions: Ensure your role has "Author" or "Admin" privileges. While all team members can view decisions, only authorized users can move a decision from Draft to Accepted status.

• Associated Memories: While not strictly required for technical creation, it is highly recommended that you have already captured the relevant context as Memories. Linking a decision to its underlying reasoning is essential for long-term preservation.

• Hopsule CLI (Optional): If you prefer terminal-based workflows, ensure the Hopsule CLI is installed and authenticated via a secure token.

Method 1: Creating a Decision via the Hopsule Dashboard

The Hopsule Dashboard provides the most comprehensive interface for decision management, offering a rich text environment and direct access to the Knowledge Graph for conflict detection.

Step 1: Access the Decision Module

Log in to your Hopsule account and select your project from the organization sidebar. Click on the Decisions tab in the primary navigation menu. This view displays your current decision registry, categorized by their lifecycle state (Draft, Pending, Accepted, Deprecated).

Step 2: Initiate the Creation Process

Click the Create Decision button located in the top-right corner of the interface. This will open the Decision Editor, a dedicated workspace designed to capture the nuance of your organizational judgment.

Step 3: Define the Decision Identity

Every decision requires a clear, authoritative identity to ensure it is easily identifiable within the Knowledge Graph and IDE extensions:

• Title: Use an imperative, concise statement (e.g., "Use Functional Components for UI Logic" or "All API Responses Must Follow Envelope Pattern"). Avoid vague titles.

• Summary: Provide a high-level overview of the decision. This text is what developers will see first in Hopsule for VS Code when a contradiction is detected.

• Tags: Assign relevant tags to categorize the decision. Tags are critical for the Knowledge Graph (Brain) to visualize relationships between disparate decisions.

Step 4: Establish Reasoning and Context

This is where Hopsule differentiates itself from traditional tools. A decision without reasoning is merely a rule; a decision with reasoning is a memory. In the Reasoning section, you should link existing Memories. These are append-only entries that explain the "why" behind the "what." By linking memories, you provide future developers with the history and lessons that led to this specific enforcement.

Step 5: Assign to Context Packs (Capsules)

Decisions are most effective when they are portable. In the Context Packs dropdown, select which capsules should include this decision. For example, a decision about database indexing might belong to both a "Backend Standards" capsule and a "Performance Optimization" capsule. This allows the decision to be shared across multiple projects and AI sessions via Hopsule MCP.

Step 6: Set Initial Lifecycle State

By default, new decisions are created in the Draft state. This allows you to refine the language and reasoning before it becomes an enforceable constraint. Once you are satisfied, you can move it to Pending for team review, or if you have the authority, move it directly to Accepted. Only Accepted decisions trigger warnings in Hopsule for VS Code.

Method 2: Drafting with Hopper (AI-Assisted)

Hopper, our built-in AI assistant, can help you draft decisions based on natural language descriptions or existing team memories. Hopper uses RAG (Retrieval-Augmented Generation) to ensure that new drafts do not contradict existing governance.

1. Open the Hopper assistant panel within the Hopsule Dashboard.

2. Provide a prompt such as: "Draft a decision regarding our migration to asynchronous event processing based on the discussion memories from last week."

3. Hopper will analyze your team's existing memories and suggest a structured decision, including a title, summary, and suggested tags.

4. Review Hopper's suggestion. Note: Hopper is advisory only. It cannot finalize or accept a decision. You must click Convert to Draft to move the suggestion into the formal decision registry.

5. Hopper will also flag potential conflicts. If your new draft contradicts an existing Accepted decision, Hopper will highlight this in the Conflict Detection panel, allowing you to resolve the discrepancy before the decision is published.

Method 3: Creating a Decision via Hopsule CLI

For developers who live in the terminal, the Hopsule CLI offers a streamlined way to preserve decisions without leaving the development environment. This is particularly useful for capturing decisions made during pair programming or architectural spikes.

The Interactive TUI Workflow

Run the following command in your terminal:

This launches the interactive Terminal User Interface (TUI), featuring ASCII art and a structured form. You will be prompted to enter the title, summary, and tags. The CLI also allows you to search for existing memories to link as reasoning directly from the terminal.

The Direct Command Workflow

For faster entry, you can use flags to define the decision in a single line:

Upon successful creation, the CLI will return a unique Decision ID and a link to view the entry in the Hopsule Dashboard. These decisions are immediately synchronized with the central authority and will appear in the Knowledge Graph for the rest of the team.

Decision Lifecycle and Enforcement

Understanding the lifecycle of a decision is crucial for effective governance. Hopsule ensures that "enforcement is remembrance, not control" by guiding decisions through specific stages:

Tips and Best Practices

• Be Atomic: Each decision should cover a single, specific constraint. Instead of a broad "Frontend Standards" decision, create separate decisions for "Component Naming," "State Management," and "CSS Architecture."

• Always Link Memories: A decision without reasoning is likely to be ignored or eventually overturned. Linking at least one Memory ensures the "why" survives even after the original authors have left the organization.

• Use the Knowledge Graph: Before finalizing a decision, check the Brain view in the Hopsule Dashboard. Visualizing how your new decision connects to existing ones helps prevent contradictory governance.

• Leverage Context Packs: Organize your decisions into logical Capsules. This makes it easier to onboard new developers by simply sharing the "Core Architecture" or "Security Protocols" Context Pack.

• Regular Audits: Periodically review your Accepted decisions. If a decision is no longer relevant, move it to Deprecated rather than deleting it. Remembrance requires keeping the history of what was once decided.

Troubleshooting

If you encounter issues while creating or managing decisions, refer to the table below for common causes and resolutions.

Related Articles

• Understanding the Decision Lifecycle: From Draft to Deprecated

• Managing Context Packs (Capsules) for Portable Governance

• Using the Knowledge Graph to Visualize Organizational Memory

• Setting Up Hopsule for VS Code for Real-Time Enforcement