Searching and Filtering Decisions

As an engineering organization grows, the volume of preserved judgment and formal commitments naturally expands. Effective governance relies on the ability to retrieve these decisions at the precise moment they are needed for enforcement or context. This article provides an exhaustive guide on how to navigate the Hopsule decision layer, ensuring that your team’s collective memory remains accessible, searchable, and actionable across all product surfaces.

Prerequisites

Before utilizing the advanced search and filtering capabilities of Hopsule, ensure you have met the following requirements:

• An active account with access to your organization’s Hopsule Dashboard.

• At least one project or Context Pack (Capsule) populated with decisions in various lifecycle states (Draft, Pending, Accepted, or Deprecated).

• The Hopsule CLI installed and authenticated if you intend to perform terminal-based queries.

• The Hopsule for VS Code extension installed for in-editor decision retrieval.

Searching the Decision Layer

Hopsule treats decisions as first-class entities. Unlike traditional text-based systems, searching in Hopsule involves querying a structured memory system that understands the relationship between authority, reasoning, and time. You can search for decisions using several methods depending on your current workflow.

Global Search in the Hopsule Dashboard

The Hopsule Dashboard features a centralized search interface designed for rapid retrieval of organizational judgment. To use the global search:

1. Navigate to the Decisions tab in the left-hand sidebar of the Hopsule Dashboard.

2. Locate the Search Decisions input field at the top of the main content area.

3. Enter keywords related to the decision title, the problem it solves, or the specific Memories linked to it.

4. The results will update in real-time, displaying the most relevant decisions based on text matches and metadata.

The global search does not just look at titles; it indexes the entire context of a decision, including the append-only Memories that explain the reasoning behind the commitment. This ensures that even if you forget the exact title of a decision, you can find it by searching for the "why" preserved in its history.

Natural Language Retrieval with Hopper

Hopper, the built-in AI assistant, provides a conversational interface for searching the decision layer. Instead of keyword matching, Hopper uses RAG-powered context awareness to interpret intent.

1. Open the Hopper chat interface from the bottom-right corner of the Hopsule Dashboard or via the Hopsule for VS Code sidebar.

2. Ask a question such as, "What is our current decision regarding database indexing?" or "Why did we deprecate the previous authentication flow?"

3. Hopper will query the decision layer and Memories to provide an authoritative answer, citing specific decisions and their current lifecycle status.

It is important to remember that Hopper is advisory. It retrieves existing governance to assist your judgment; it never alters the state of a decision autonomously.

Command-Line Search via Hopsule CLI

For developers who prefer to remain in the terminal, the Hopsule CLI offers powerful search commands. This is particularly useful for checking enforcement constraints before committing code.

1. Open your terminal and ensure you are within a project directory linked to a Hopsule Context Pack.

2. Execute the command hopsule list to see all decisions associated with the current context.

3. Use the --search flag followed by your query: hopsule list --search "security".

4. To see the full details of a specific decision, including its Memories, use hopsule view [DECISION_ID].

Advanced Filtering and Categorization

Search is often most effective when combined with granular filters. Hopsule allows you to narrow down the decision layer based on lifecycle, ownership, and custom taxonomy.

Filtering by Lifecycle State

Decisions in Hopsule move through a formal lifecycle. Filtering by state is essential for distinguishing between active enforcement and historical record.

• Draft: Decisions currently being authored but not yet proposed.

• Pending: Decisions awaiting review and formal acceptance by the team.

• Accepted: The active governance of the organization. These are enforceable constraints.

• Deprecated: Historical decisions that are no longer active but are preserved for organizational memory.

To apply a lifecycle filter, click the Status dropdown menu in the Hopsule Dashboard and select one or more states. For example, filtering by Accepted ensures you are only looking at the rules currently in effect.

Tag-Based Filtering

Tags allow you to categorize decisions by domain, such as #architecture, #security, #frontend, or #compliance. To filter by tags:

1. Click the Filter button next to the search bar.

2. Select the Tags option.

3. Choose the relevant tags from the multi-select list.

4. The dashboard will refresh to show only decisions that carry those specific organizational markers.

Author and Ownership Filters

Governance is often tied to specific individuals or sub-teams. You can filter decisions by the "Owner" (the person responsible for the decision) or the "Author" (the person who originally drafted the entry). This is particularly useful during performance reviews or when seeking further clarification on a specific piece of organizational judgment.

Visual Search via the Knowledge Graph

Hopsule provides a Knowledge Graph (also referred to as the Brain) that visualizes the relationships between decisions, Memories, and Context Packs. This is a non-linear way to search for information.

1. Select the Brain icon from the Hopsule Dashboard navigation.

2. Use your mouse to zoom and pan through the nodes representing your organization's memory.

3. Click on a node to see the decision it represents and its outgoing links to other related decisions.

4. Use the Graph Search bar within this view to highlight specific clusters of decisions based on your query.

The Knowledge Graph is invaluable for understanding the "blast radius" of a decision—how one choice influences others across different projects or Context Packs.

Searching within Hopsule for VS Code

The Hopsule for VS Code extension brings the decision layer directly into the developer's environment. This prevents context switching and ensures that remembrance happens where the work occurs.

1. Open the Hopsule view in the VS Code Activity Bar.

2. Use the Decision Explorer tree view to browse decisions by their Context Pack.

3. The search icon at the top of the Decision Explorer allows you to filter the tree view by keyword.

4. When a decision is selected, its full history and linked Memories are displayed in the editor sidebar, providing immediate context for the code you are writing.

Tips and Best Practices

• Use Descriptive Tags: Consistent tagging across the organization makes filtering significantly more powerful. Establish a standard set of tags for common domains.

• Leverage Append-Only Memories: When searching, remember that Memories are never deleted. If you cannot find a decision by its title, try searching for the names of contributors or specific technical trade-offs mentioned in the reasoning.

• Regularly Review Deprecated Decisions: Use the Deprecated filter to understand why past approaches failed. This prevents the organization from repeating historical mistakes.

• Context Packs as Search Scopes: Use Context Packs (Capsules) to narrow your search scope. If you are working on a specific microservice, filtering by that service's capsule will remove irrelevant noise from other parts of the organization.

• Ask Hopper for Summaries: If a search returns too many results, ask Hopper to "Summarize all accepted decisions related to API design" to get a high-level overview of the relevant governance.

Troubleshooting

If you encounter issues while searching or filtering within the Hopsule ecosystem, refer to the table below for common causes and solutions.

Related Articles

• Managing the Decision Lifecycle: From Draft to Deprecated

• Understanding Context Packs and Capsules

• Using Hopper for Contextual Reasoning

• Enforcing Decisions in VS Code and Cursor