modify recommendation CQL to replace recommendation text with keys

[mattStorer]

per conversations we had before the holiday break, would like to replace recommendation text blocks in CQL with unique keys, as a matter of improved separation of concerns, and to simplify future modifications to recommendation text, and to make possible the provision of alternate text given certain scenarios (e.g. during A-B testing).

as a product of this process, please compile a basic spreadsheet of key-value pairs (key=recommendation text block) so that I can use that to build out the COACH database table where those associations can be made.

this issue is a companion to issue OHSUCMP/coach#24

[aeyates]

@mattStorer I had been hoping for more discussion before we jumped on this idea. We will need to figure out how to deal with CQL values that were previously dynamic. For example, goal suggestions use a unique id to avoid conflict with other goals, so it looks something like this:

And when it's time to update a goal, the CQL returns the text of the goal as part of the suggestion:

Either COACH will have to do substitutions of this dynamic information or the CQL will have to pass "metadata" associated with the key. Since COACH has the information, I'd vote for the first option, but I need to give it some more thought.

I'm starting to compile a document starting with the easier workflows. I'm going to keep the pipe-delimited convention for details with individual keys for rationale, suggestions, etc. And I'm only considering keys for summary and detail right now, but can do them for indicator and source if you want a fully generic implementation. So a cards response might look something like this:

{
    "cards": [
        {
            "summary": "Hypertension.5-ConsiderStage1.Summary",
            "indicator": "info",
            "detail": "Hypertension.5-ConsiderStage1.Rationale|Hypertension.5-ConsiderStage1.Suggestions|Hypertension.SelectionBehavior|Hypertension.5-ConsiderStage1.Links",
            "source": {}
        }
    ]
}

[mattStorer]

@aeyates ah, okay thanks for this information. please note that there is no set timeline on doing any of this, I'm just trying to document plans for future development and get the ball rolling, even if that just means exploring what it might take to accomplish it. no stress, no rush.

I think that mostly all we will really want to adjust is the label component, we probably don't want to try to reduce entire recommendations down to a single key. there is probably a viable middle-ground to be found here.

[aeyates]

Thanks for the added context. It will be good to get some specifics on what type of variation the team wants in messaging for the clinical trial. If it would be sufficient to provide keys for the summary and details in the graphic below, but leave suggestions, links, and other things static, that would be an easier lift.

[mattStorer]

For sure. We will definitely want to identify which recommendation components should be variable, and which are safe to keep static. I'm not sure off the top of my head where the line should be drawn, though - I suspect we will want to raise this topic with the larger team for comment. What I can say is that the driving use-case for this relates to A-B testing, which is something that has been discussed in meetings. However, the details of how A is to differ from B has yet to be defined.