When a Jira Issue Disappears: Lessons from Building a Cognee Connector

When a Jira issue disappears from a search result, should its information vanish entirely from the connected system? The question of what happens to data when Jira stops returning a particular piece of information became a valuable lesson in building a connector for Cognee.

The initial focus was on creating a connector that could read Jira issues, comments, and attachments, turning them into searchable documents within Cognee. However, the real challenge emerged once Jira stopped returning certain data. Should Cognee forget about that data? This question transformed a simple connector project into an exploration of uncertainty and the importance of thorough testing.

To begin, a free Jira Cloud test site and a small synthetic project were created, filled with fabricated issues, comments, and attachments. This allowed the team to know exactly what the connector should find, modify, and remove without introducing real-world data early on. After the first synchronization, the connector successfully created five documents: two issues, two comments, and one attachment.

During testing, the team discovered several key insights. First, simply relying on search results was not enough evidence that removed content had truly been cleaned up. Cognee needed a mechanism to verify that the data had been permanently deleted. The team developed two policies for handling missing data: mirroring visibility, which updates the local corpus to reflect current access, and requiring confirmation, which pauses the process when known documents disappear and allows the caller to check and confirm specific removals.

Neither policy guarantees that absence equals deletion, so these choices should be made explicitly in configuration and documentation.

Further reviews uncovered additional issues. For instance, the connector's renderer mistakenly flattened superscript and subscript, altering the meaning of expressions containing superscripts. Additionally, the connector failed to properly reconcile issue IDs after reconciliation, allowing issues to reappear in search results even when they no longer matched a JQL filter. These bugs were addressed through iterative reviews, small reproductions, and the addition of regression tests.

Another important lesson came from the discovery that a simple ordering clause in a JQL query could cause the connector to reject valid filters. This was fixed by distinguishing quoted JQL values from actual ordering clauses. The team also realized the importance of validating what their tests were actually loading and intercepting, rather than blindly trusting the test's name or exit code.

The final version of the connector passed 69 tests across multiple Python versions and included tests for Jira lifecycle recovery, cleanup after downstream ingestion failure, and handling of staged resources. While the team verified many aspects of the connector, some unknowns remained, highlighting the ongoing challenges in ensuring data consistency and integrity in complex systems.